@cratis/pi 7.61.0 → 7.63.0

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

@@ -0,0 +1,82 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Described command handlers
+
+Requires Screenplay 4.182.0 or later (`screenplay --version`); older compilers refuse pending handlers with PLAY0268.
+
+Use a described command when payload computation needs words rather than an invented
+expression. Prefer ordinary `produces` when the logic is declarative. Do not use a
+described body to reject a command or decide how many events to emit.
+
+Complete model:
+
+```screenplay
+domain Billing
+module Invoices
+  feature Fees
+    slice StateChange ApplyLateFee
+      command ApplyLateFee
+        invoiceId String identifier
+        daysOverdue Int
+        validate
+          daysOverdue >= 1 message "The invoice must be overdue"
+        handler
+          implementation
+            hint "Calculate the late fee from overdue days using the agreed daily rate"
+        produces LateFeeApplied
+          for invoiceId
+      event LateFeeApplied
+        amount Decimal
+```
+
+A pending `implementation` has no `file` or fence. Bare `implementation` is valid;
+optional `hint` lines are ordered, nonblank quoted strings, decoded without trimming.
+One wrapper and at most one payload are permitted. Attaching a file or fence stops
+being a described command: attached handlers still fail binding with PLAY0268 and
+cannot coexist with `produces`.
+
+## Result contract v1
+
+| Part | Owner |
+| --- | --- |
+| Events, count, order | Declarative; each unconditional `produces` means exactly one event |
+| Destination, routes, allocation, tags and metadata | Declarative |
+| Generated values and response | Declarative; generation precedes the body |
+| Authorization and validation | Declarative; denial or refusal never reaches the body |
+| Event payload values | Body; mappings are non-normative hints, required properties may be unmapped |
+
+Mapping type checks still apply. Neither a renderer nor reference execution evaluates
+these payload mappings. Conditional productions, repeated/occurrence productions,
+body-decided cardinality and body rejection are outside this contract.
+
+The command selects ESM v23 with `handler: { requirementId, resultVersion: 1 }`.
+The requirements sidecar carries a Pending CommandHandler requirement with ordered
+hints, context/result versions 1, and provisional/ambiguous flags. Consumers must
+explicitly admit this version, never silently drop the body.
+
+| Diagnostic | Meaning and action |
+| --- | --- |
+| PLAY0695 (information) | Described command admitted; command and RequirementId name the missing body |
+| PLAY0696 (error) | No productions, including response-only; add unconditional productions |
+| PLAY0697 (error) | Conditional productions; result v1 needs unconditional events |
+| PLAY0698 (error) | Pending intent plus another handler; keep one handler |
+| PLAY0492–0494 | Invalid wrapper, hint or payload composition; fix the source shape |
+
+## Execution and realization
+
+Reference execution runs the gates, routing and generation in ordinary order, then
+returns Unsupported (`ImplementationBody`) on reaching the body, naming command and
+RequirementId. This also applies through an invoking reaction. No payload mapping runs
+and no event is emitted. Denial and validation specifications still execute. Unsupported
+specifications are counted separately; an all-Unsupported run is never green.
+
+Stage admits v23 but refuses described handlers with STAGE-IMPL-002 in the renderer,
+Host and specification executor, including Stub mode: it emits no stubs. Hand-write
+the body against the declared contract as authorized gap-fill; do not claim that a
+pending requirement is implementation evidence. Moving the body into `handler file`
+keeps its RequirementId but does not admit that attached handler alongside `produces`.
+
+Validate the model root with `screenplay <root> --warnaserror`; expect no errors or
+warnings and PLAY0695 information. Run `screenplay test <root>` separately: body-reaching
+specifications must be reported Unsupported, not passed. Target tests are separate.

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

@@ -1,4 +1,4 @@
-# Generated values and responses (ESM v7 and v15)
+# Generated values, rule proofs and responses
 
 ## Contents
 
@@ -28,16 +28,17 @@ Only the released generation phase is taught here.
 ## Choosing a strategy
 
 Use the [threaded shop model](shop-generation.md): CustomerId is `cus_` + ULID,
-OrderId is TypeID, InviteCode is NanoID. It links the same .NET concepts but does
-not claim their received-time/tenant context or secret ApiKey Bytes(32) factory
-is executable in Screenplay. The table below owns exact strategy shapes.
+OrderId is TypeID, InviteCode is NanoID, InvoiceNumber is a readable pattern with
+Luhn check digit, and TicketNumber is a random Int value. Keep short references
+separate from event-source identities. The table below owns exact strategy shapes.
 
 ## When not to
 
 Client-minted values remain inputs. Generation is not authorization, idempotency,
-gapless invoice allocation or a credential contract. Preserve ApiKey's `secret`
-classification without generated properties; context/secret execution remains
-Screenplay#616 phases 3/4, not a reason to strip protection.
+gapless/sequential invoice allocation or a credential contract. A pattern is not
+an allocator; check digits catch typing mistakes, not forgery. Preserve ApiKey's
+`secret` classification without generated properties: generated secrets remain
+refused, not a reason to strip protection.
 
 ## The concept declares how; the property declares that
 
@@ -46,7 +47,7 @@ strategies on concepts and `generated`/`generated identifier` on properties.
 It includes whole-value fixture pins and returned IDs.
 
 A generated property must be a required scalar **concept**, not a bare primitive,
-optional value or collection. Only Uuid and String generation are executable.
+optional value or collection. Uuid/String generation and Int `random` are executable.
 A Uuid concept implicitly generates `uuid`; String needs an explicit strategy.
 Each concept owns at most one `generate` line; there is no per-property override.
 Generated identifiers need Uuid or String backing and at least 64 random bits.
@@ -59,6 +60,9 @@ Generated identifiers need Uuid or String backing and at least 64 random bits.
 | `typeid "user"` | String | TypeID 0.3, lowercase Crockford UUIDv7 suffix; 74 random bits; prefix 1–63 lowercase letters/underscores, no leading/trailing underscore; empty prefix omits separator |
 | `nanoid [size]` | String | Default 21 symbols from `A-Za-z0-9_-`; size 1–256; entropy is size × log2(alphabet size) |
 | `bytes <count> base64url` / `hex` / `base32` | String | Count 1–512; 8 × count random bits; RFC 4648 without padding; hex lowercase, base32 uppercase; unused trailing bits zero |
+| `pattern "INV-{yyyy}{MM}-#{7}" checksum luhn` | String | Finite readable reference; UTC dates and check digits add no entropy |
+| `random 100000..999999` | Int | Inclusive signed Int64 interval; numeric value, not an identifier |
+| `rule Name` | String | Exactly one file or tagged fence; opaque ValueGeneration implementation with language-neutral Now/Tenant context, String result and unknown entropy |
 
 Modifiers occur once each, in any authored order. `prefix "text"` is printable
 ASCII, at most 32 characters, on uuid/uuidv7/ulid/nanoid/bytes; UUID prefixes need
@@ -71,17 +75,31 @@ identifier; non-identifiers warn PLAY0683 unless a single-property unique
 constraint covers the mapped event property. That suppression is not a runtime collision guarantee; use the constraint when
 collisions must reject the command.
 
-`pattern`, `random`, `rule` and checksum syntax parse/print but refuse PLAY0268;
-`generate sequence` is reserved (PLAY0682). Generated-concept validation rules select ESM v20; compliance markers, including
-generated secrets, remain refused. Do not
-remove classification or pretend a random String is a credential contract.
+Requires Screenplay 4.172.0 or later (`screenplay --version`) for pattern/random/rule
+and String-concept `validate checksum luhn|mod11|mod97` (ESM v21); older compilers
+refuse them with PLAY0268. Pattern `#` draws a digit, `?` an uppercase letter,
+`*` an uppercase letter or digit; positive ASCII classes and `{n}`/`{m,n}` repeats
+up to 64 are supported. `{yyyy}`, `{yy}`, `{MM}`, `{dd}` use one UTC date.
+The expanded value, including check digits, is at most 256 characters. Only pattern
+accepts `checksum`; write literals/classes rather than prefix/case/alphabet modifiers.
+Read Cratis/Screenplay `Documentation/screenplay/generated-values/patterns.md`
+for escaping and support limits. PLAY0691 means support counting exhausted its
+budget; PLAY0692 means some date in the 100-year assessment horizon has empty
+support. Neither is a proof warning or permission to redraw.
+
+Checksum generation appends one Luhn/Mod11 digit or two Mod97 digits over preceding
+ASCII digits, including date/literal digits. Author `validate checksum` separately
+for arithmetic validation of supplied/stored values and fixtures; generation alone
+checks only suffix shape on fixtures. `generate sequence` stays reserved (PLAY0682),
+and compliance markers on generated concepts, including secrets, remain refused.
+Never remove classification to make a model bind.
 
 ## Inspect and edit generation through MCP
 
 A concept `generation` summary and entropy repairs are available.
 Use `screenplay_declaration_details` with `kind: "Concept"`, `view: "summary"`:
 only authored `generate` gets a block, with strategy, set modifiers,
-preview-only arguments, `entropyBits`, `entropyUnknownReason` when null,
+`arguments`, `supportCount`, `entropyBits`, `entropyUnknownReason` when null,
 `valuesAtOnePercentCollision` and `executable.status`. Status is `admitted` only
 after whole-model binding, `refused` for errors at this concept/generation, or
 `notAssessed` with a reason for unrelated binding failures. Empty local codes do
@@ -91,7 +109,7 @@ Set/change/remove `generate` through `screenplay_propose_ast` (replace the conce
 `GenerationSyntax`, omit/null `generation` to remove) or reviewed
 `screenplay_propose_source`; do not hand-edit the text. Inspect executable
 diagnostics independently of authoring acceptance: sequence PLAY0682;
-pattern/random/rule PLAY0268; generated-rule proofs PLAY0688/0689. Review, run candidate
+support failures PLAY0691/0692; generated-rule proofs PLAY0688/0689. Review, run candidate
 specifications where executable, then apply with revisions.
 
 `screenplay_repair_capabilities` advertises PLAY0683/0684; workspace repairs supply
@@ -104,12 +122,19 @@ individual review and `CanonicalizeTouchedDocuments`, with no pinned evidence.
 Length changes affect all concept uses; uniqueness changes append-time behavior.
 PLAY0688 repair replaces a refuted rule with the strategy-derived `matches`
 pattern. Review input/stored-value uses because this changes their validation,
-not just generation. Checksum repairs remain unadmitted.
+not just generation. A deterministic bounded pattern repair also adds the declared
+checksum validation if absent; review both rule changes. Ambiguous derived regexes
+have no repair. Date/checksum digit shapes alone do not prove containment.
 A CLI-bundled MCP can lack this summary and these repairs; it still
 supports existing typed concept proposals.
 
-Requires Screenplay 4.149.0 or later (`screenplay --version`) for the concept `generation` summary and entropy repairs. Full fields, mapping limits and tagged
-source evidence: [MCP generation guide](../../cratis-screenplay-model-authoring/references/mcp-tools.md#concept-generation).
+Requires Screenplay 4.173.0 or later (`screenplay --version`) for `arguments`,
+exact support counts, `derivedPattern` and authored-order `rules[]`; older servers
+can expose `previewArguments` instead. Read `rules[].status`, `witness` and `reason`
+instead of parsing diagnostic text. Use `derivedPattern` as `matches` through a
+typed proposal; use the discovered PLAY0688 repair to replace a refuted rule.
+A refuted rule without `diagnosticCode` was not checked by the compiler (for example,
+an unused UUID concept), so do not invent a repair. Full fields and mapping limits: [MCP generation guide](../../cratis-screenplay-model-authoring/references/mcp-tools.md#concept-generation).
 Sources: Cratis/Screenplay `Documentation/screenplay/generated-values.md`,
 `Source/DotNET/Screenplay.Mcp/McpGenerationDetails.cs`,
 `Source/DotNET/Screenplay/Workspaces/WorkspaceGenerationRepairs.cs`.
@@ -135,20 +160,27 @@ that cannot backtrack on generated values. Passing samples alone prove nothing.
 Providers validate generated values too: a failing fixture is a Contract violation,
 not client rejection or a reason to redraw. Opaque rules need a target.
 
-Rules select v20 even on implicit UUID generation. No proof status is serialized;
+Generated-concept validation rules select ESM v20 even on implicit UUID generation.
+No proof status is serialized;
 strategy changes do not silently change rules on stored/input values.
 
+Tool and renderer authors: read the toolchain's
+[generation checks](../../cratis-screenplay-toolchain/references/generation-checks.md)
+for declaration checks, value checks, strategy discovery and rule proofs.
+Proof status is not serialized; the reference evaluator always requires pins.
+
 ## Version and freshness
 
 A serialized concept `generation` member selects **v15**. Implicit Uuid generation
 and explicit unmodified Uuid `generate uuid` omit it and preserve earlier executable
-bytes/revision. A v15 model guards **all** generated destinations, including its
-implicit UUIDs. An append whose destination equals any value generated in that
+bytes/revision. Any model with a serialized strategy guards **all** generated destinations,
+including its implicit UUIDs; ESM version alone does not enable the guard. An append whose destination equals any value generated in that
 invocation requires the **whole source** to have no existing facts, regardless
 of stream or event type. Multiple initial facts in one invocation are allowed;
 a skipped production makes no freshness claim. Reuse rejects the whole command
 with `Concurrency`, appends nothing and does not silently regenerate or retry.
-Older models are Unguarded and retain legacy fixture reuse.
+Models without a serialized strategy are Unguarded and retain legacy fixture
+reuse, even if rules select v20.
 
 Freshness is neither authorization nor idempotency. Client-minted identifiers
 remain inputs; protect their invariants with constraints. Never use generation
@@ -158,7 +190,12 @@ Specifications pin values, not seeds: `for` pins a generated identifier;
 `generated <name> = <value>` pins another generated property. The reference
 evaluator draws no randomness. From v15 every pin must match exact strategy
 encoding, size, case, UUID version/variant and zero trailing bits. Invalid pins
-are Contract rejections, not client validation failures. Older models retain
+are Contract rejections, not client validation failures. Rule-bearing concepts
+also check rules, including implicit UUID. Pin date segments with `given clock`;
+all segments must match the same UTC instant. Without a clock only digit widths
+are checked, never the wall clock. Opaque generation rules consume String pins
+without executing attached code; opaque validation still yields Unsupported.
+Older rule-free implicit-UUID models retain
 canonical UUID checks without a version check. Complete executable examples:
 [generated responses](../../cratis-screenplay-toolchain/references/generated-responses-example.md)
 and [generation strategies](../../cratis-screenplay-toolchain/references/generation-strategies-example.md).
@@ -188,7 +225,7 @@ and [generation strategies](../../cratis-screenplay-toolchain/references/generat
 ## What the CLI and Stage realize
 
 Stage emits strategy-specific `IGeneratable<T>.New()` factories over Fundamentals
-7.24.0 or later (via the Arc scaffold pin in Stage's `references/rendered-application.md`). v15 generated destinations use explicit
+7.25.0 or later for pattern/random/checksum (via the Arc scaffold pin in Stage's `references/rendered-application.md`). v15 generated destinations use explicit
 `EventsWithConcurrencyScopes` with `BeforeFirst` whole-source scopes; Chronicle
 checks atomically at append: a batch's scopes are checked once against the state before
 the batch, all or nothing, and a storage retry that renumbers the append checks them again. Generated rejection specs assert
@@ -201,10 +238,12 @@ Requires Stage 4.94.0 or later for receipt-time generation; older factories use
 
 | Refusal | Still unsupported |
 | --- | --- |
-| STAGE-ESM-028 | Unknown strategies, non-concepts, optional/collection generation; every explicit strategy on the legacy syntax engine |
-| STAGE-ESM-011 | A v15 fixture that does not match its strategy shape |
-| STAGE-ESM-038 | Routing combined with generation/responses; generated-property rules/requirements or concept rules; occurrence parameter/response/factory name collisions; unsupported response sources/composites/collections; generated identifier plus destination-less plain production |
-| STAGE-ESM-038 | Unpinned generation with unordered event, read-model or query expectations |
+| STAGE-ESM-028 | `generate rule`, unknown strategies, non-concepts, optional/collection generation; every explicit strategy on the legacy syntax engine |
+| STAGE-ESM-011 | A fixture that does not match its strategy shape or concept rules |
+| STAGE-ESM-038 | Routing combined with generation/responses; generated-property rules/requirements; occurrence parameter/response/factory name collisions; unsupported response sources/composites/collections; generated identifier plus destination-less plain production |
+| STAGE-ESM-038 | Unpinned generation with any Unproven/Refuted concept rule, production-condition reads, unordered event/read-model/query expectations or collision-sensitive generated constraints |
+| STAGE-ESM-042 | Unsupported concept-rule kinds; checksum remains refused only on the legacy syntax path |
+| STAGE-ESM-005 | Opaque/unsupported generated-concept rules, before pin evaluation |
 | STAGE-ESM-004 / -006 | StateChange slices without commands / expression or enum production conditions |
 
 Sequence generation is refused at binding (PLAY0682) and never reaches Stage;
@@ -213,7 +252,22 @@ command `given clock` fixtures render when whole milliseconds at or after 1970;
 
 Requires Stage 4.95.0 for command clock fixtures, 4.98.0 for multiple commands and
 conditional productions, and 4.100.0 for generated text unique constraints; older
-renderers refuse those shapes. ESM v20 still needs a renderer that admits v20.
+renderers refuse those shapes.
+
+Requires Stage 4.109.0 for ESM v20 factories plus `ConceptValidator`; older renderers refuse v20.
+Requires Stage 4.115.0 for ESM v21 admission and all-Proven unpinned generation;
+older renderers require pins even for Proven rules. Unproven/Refuted rules still
+require pins (-038), and invalid pins fail -011.
+Requires Stage 4.117.0 for warning/info-severity generated-concept rules; older
+renderers refuse them with -038. Every severity is enforced as a generation defect.
+Requires Stage 4.118.0 for semantic checksum validation and 4.119.0 for
+pattern/random factories, Host sampling and executor fixture checks; older
+renderers refuse those constructs with -042/-028. Dated patterns use receipt-time
+context; Int ranges render as `long`. `generate rule` still refuses -028.
+Requires Arc.Screenplay 22.107.0 for pattern/random/checksum and self-contained
+String-rule recovery; older adapters leave these factories in code. Recovery is
+not Stage rendering: keep refused rule contracts for gap-fill, never delete rules
+or secret classification.
 
 Missing pins in generated Debug specs use `AllowGeneration()` with relational
 assertions against captured values; v15 captures also check strategy shape.

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

@@ -0,0 +1,113 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Protected command reads
+
+## Contents
+
+- Admission and paths
+- Absence and races
+- Repair and target boundary
+
+Requires Screenplay 4.193.0 or later (`screenplay --version`); older compilers refuse command reads with PLAY0271 and read paths with PLAY0268.
+
+Declare `command reads protected` once in the application-root document. Imported
+commands inherit it. This selects ESM v25, including when text rules are used, and
+records `commandReadMode: "protected"`. Without it, legacy reads retain PLAY0271,
+read paths retain PLAY0268, and bytes/version stay unchanged. A higher ESM version
+alone never opts an application in.
+
+Complete model:
+
+```screenplay
+domain Inventory
+command reads protected
+module Stock
+  feature Allocation
+    slice StateView CurrentStock
+      event StockCounted
+        quantity Int
+      event StockRemoved
+      readmodel Current
+        id String key
+        quantity Int
+      projection CurrentProjection => Current
+        from StockCounted
+        remove with StockRemoved
+    slice StateChange Allocate
+      command Allocate
+        id String identifier
+        stockId String
+        reads Current by stockId
+        validate
+          require Current.quantity > 0
+            message "Stock must be available"
+        produces Allocated
+          for id
+          quantity = Current.quantity
+      event Allocated
+        quantity Int
+```
+
+## Admission and paths
+
+`reads <View> [as <alias>] [by <input>]` looks up required state. Omitted `by` uses
+the declared command identifier; no identifier is PLAY0782. Repeated reads of a
+view each need a distinct alias; paths use the alias rather than the view name.
+Aliases start with a lowercase letter or underscore.
+
+Every read must satisfy both boundaries:
+
+- A finite non-empty set of event-log event types builds the view, including removal
+  handling; the key is event-source identity only.
+- The lookup key is a required scalar non-generated command input: String, a String
+  concept or canonical GUID.
+
+PLAY0781 refuses reducers, joins (including removal joins), children/nested scopes,
+`every`/`all`, payload/composite keys, missing removals, empty handled-event sets,
+named sources/streams, singleton views and unsupported/generated/optional/collection
+keys. Its closed reasons are Reducer, Join, Children, OpenSubscription, PayloadKey,
+ByParts, NoRemoval, EmptyHandledSet, NamedSourceOrStream, Singleton, KeyType,
+GeneratedKey, OptionalKey and CollectionKey. `optional`, `advisory` and `via query`
+remain refused; `via query` uses parser code PLAY0175. There is no unguarded fallback.
+
+Single-level `read.property` paths bind in `require` operands and produced-event
+mapping sources only. Deeper paths and read paths in `produces when`, response
+fields, `for`, routes and derive/provide remain PLAY0268. Unknown read/property
+paths report PLAY0784; ambiguous view paths report PLAY0785. A command with both
+`reads` and `concurrency` reports PLAY0783: do not guess which boundary wins.
+
+## Absence and races
+
+Execution orders authorization → property rules → required reads → derive/provide
+→ requirements → productions/responses. Missing state rejects with Validation and
+message `<ReadModel> '<key>' does not exist.` before evaluating requirements or
+mappings. Property-rule rejection therefore wins over absence.
+
+Decide records the unfiltered fact-log boundary, read key and handled event types.
+A matching fact after that boundary makes commit return Conflict /
+DecisionStateChanged with no command facts, including publications. Irrelevant
+facts do not conflict and remain in the committed world. Even a no-fact command is
+checked. Race cases are evaluator vectors, not a new `.play` specification construct.
+
+Specify present/absent state, rule refusal and denial. Assert no new facts and
+unchanged views on failure; use target concurrency tests to prove actual storage
+protection. Ordinary injected read models are not protected decisions; uniqueness
+still belongs in a `unique` append constraint.
+
+## Repair and target boundary
+
+PLAY0780 rejects duplicate, conflicting or non-root preambles. Informational
+PLAY0786 identifies an eligible legacy model at its first command read. Discover
+`read-workspace view=repairs`, then `propose-repair` with current workspace/catalog
+revisions and canonical formatting consent; review with `read-proposal` before
+explicit `apply`. The repair inserts into the domain document or sole document,
+refuses ambiguous roots and requires individual review, never fix-all. It changes
+absence/conflict behavior, not merely formatting.
+
+Stage admits ESM v25 but refuses protected reads with STAGE-ESM-044 in rendering,
+Host serving and specification execution; a reference pass is not Stage or Arc
+realization. Preserve the model's protection and deliver authorized hand-written
+consistency enforcement through the render-and-gap-fill workflow. Never remove
+the preamble to get a render. `screenplay <root> --warnaserror` must exit zero;
+`screenplay test <root>` separately establishes reference behavior, not target support.

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

@@ -1,22 +1,30 @@
 <!-- Copyright (c) Cratis. All rights reserved. -->
 <!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
 
-# The shop in Screenplay: keep the release boundary
+# The shop in Screenplay: generated values
+
+## Contents
+
+- Choosing a strategy
+- When not to generate
+- Sources
 
 ## Choosing a strategy
 
 Use the same vocabulary as the [Fundamentals/Arc shop](../../cratis-fundamentals-concept/references/shop-generation.md),
 but only the released language realization: CustomerId is `cus_` + uppercase
-ULID, OrderId is `typeid "order"`, and InviteCode is NanoID. Their strategies
+ULID, OrderId is `typeid "order"`, and InviteCode is NanoID. InvoiceNumber uses
+a readable date/checksum pattern; TicketNumber is an Int pickup-ticket value. Their strategies
 belong to concepts; command properties only say `generated`/`generated identifier`.
 The existing [strategy reference](generated-values-and-responses.md) owns exact
 encodings, entropy, MCP edits, fixtures and freshness.
 
-**Context-dependent generation is not released in Screenplay.** The OrderId below
-is time-ordered TypeID, not Arc's received-time/tenant factory contract; Stage
-emits a wall-clock `New()`. Passed-through GenerationContext in Arc source
-recovery describes that strategy shape, not equivalent clock/tenant semantics.
-Context-member/rule recovery stays in code.
+Requires Screenplay 4.172.0 or later (`screenplay --version`) for pattern/random/rule
+and checksum validation (ESM v21); older compilers refuse them with PLAY0268.
+`generate rule Name` can attach code with Now/Tenant context, but the reference
+runner never executes it: pin the whole String result. TypeID itself has no
+tenant slot. Context-member factory recovery still stays in code. Stage's
+time-ordered factories use the command receipt, not an invented wall-clock value.
 
 The shop's ApiKey remains a **secret**. In .NET its factory is `Bytes(32)` and its
 concept is `[NotAudited]`. It is never an identifier (event-source IDs are plaintext
@@ -35,6 +43,11 @@ concept OrderId : String
 concept InviteCode : String
   generate nanoid
 concept ApiKey : String secret
+concept InvoiceNumber : String
+  generate pattern "INV-{yyyy}{MM}-#{7}" checksum luhn
+  validate checksum luhn
+concept TicketNumber : Int
+  generate random 100000..999999
 module Shop
   feature Customers
     slice StateChange Register
@@ -58,22 +71,39 @@ module Shop
           inviteCode = "abcdefghijklmnopqrstu"
   feature Orders
     slice StateChange Place
+      constraint UniqueInvoiceNumber
+        unique invoiceNumber on OrderPlaced
+      constraint UniquePickupTicket
+        unique pickupTicket on OrderPlaced
       command PlaceOrder
         orderId OrderId generated identifier
+        invoiceNumber InvoiceNumber generated
+        pickupTicket TicketNumber generated
         produces event OrderPlaced
+          invoiceNumber InvoiceNumber = invoiceNumber
+          pickupTicket TicketNumber = pickupTicket
         returns orderId
       specification PlacesWithPinnedValue
+        given clock "2026-10-02T09:00:00Z"
         when PlaceOrder
           for "order_0000000000e008000000000000"
+          generated invoiceNumber = "INV-202610-00000004"
+          generated pickupTicket = 123456
         then OrderPlaced
           for "order_0000000000e008000000000000"
+          invoiceNumber = "INV-202610-00000004"
+          pickupTicket = 123456
         then returns "order_0000000000e008000000000000"
 ```
 
 Each property is server-owned, not a client-minted input. The ApiKey declaration
 is not permission to replace its secret contract with an ordinary random String.
-No `given clock` is used: pin the whole value. A seed/clock does not draw a
-portable ULID or TypeID fixture. A v15 duplicate-source specification should
+The invoice date segments use the pinned UTC clock; it does not draw a portable
+ULID or TypeID fixture. Checksum validation is authored separately from generation.
+Dates/check digits add no entropy. The short invoice and ticket values use
+single-property unique constraints; neither is a generated identifier. Whole-source
+freshness protects the OrderId destination, not every generated payload value.
+A duplicate-source specification should
 expect Concurrency with no new facts or response, not a regenerated ID.
 
 ## When not to generate
@@ -83,10 +113,13 @@ idempotency keys, authorization, gapless invoice numbers or proof of projection
 readiness. A reference InviteCode is not automatically a credential; if possession
 confers access, protect it as a secret and do not claim this generated String
 example realizes that credential behavior. Never drop ApiKey's secret marker to
-make its generation bind/render. Pattern/random/rule execution, context rules,
-sequence allocation and secret generation stay explicit upstream gaps.
+make its generation bind/render. A pattern is not gapless/sequential numbering;
+check digits catch typos, not forgery. ESM v21 binds and reference-executes with
+pins. Requires Stage 4.118.0 for checksum validation and 4.119.0 for pattern/random
+rendering; older renderers refuse those constructs. `generate rule` still refuses
+STAGE-ESM-028. Sequence allocation and secret generation stay explicit gaps.
 
-## Tagged evidence
+## Sources
 
 Screenplay `Documentation/screenplay/generated-values/choosing.md`,
 `Documentation/screenplay/generated-values.md`,

package/package/corpus/skills/cratis-screenplay-command-surface/references/text-and-match-rules.md

@@ -0,0 +1,119 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Literal text rules and portable matching
+
+## Contents
+
+- Literal text rules
+- Portable `matches`
+- Studio replacements and public check APIs
+
+## Literal text rules
+
+Requires Screenplay 4.184.0 or later (`screenplay --version`) for literal text rules and pattern admission checks; older compilers do not admit these rule forms.
+
+Prefer a literal rule over a regex when the requirement is plain text. Complete example:
+
+```screenplay
+concept InvoiceReference : String
+  validate
+    contains "-"
+    not contains " "
+    starts with "INV-"
+    ends with "-NOK"
+```
+
+These concept/command-property rules select ESM v24. They compare UTF-16 code units
+ordinally, without case folding or normalization. Use one non-enum text value and a
+quoted literal operand, not a property, collection or regex. An absent optional
+value passes; add `not empty` to require presence. An empty operand makes `contains`,
+`starts with` and `ends with` pass, and `not contains` fail for present text.
+Equality and inequality remain `== "x"` and `!= "x"`.
+
+This is not condition grammar: `contains`/`starts with` in `require`, `produces when`
+or reaction `where` remain PLAY0268. Those conditions admit scalar equality and
+numeric ordering, not the property text rules.
+
+Requires Stage 4.124.0 for v24 text-rule admission (`cratis --version` identifies the CLI bundle); older renderers refuse v24 with STAGE-ESM-016.
+
+Stage admits v24 and executes these four rules on its Host and specification
+executor, rendering ordinal UTF-16 comparisons without regex or a Screenplay
+runtime dependency. The legacy EventModel syntax engine drops these rules; use
+semantic admission, never infer support from that engine's output.
+
+## Portable `matches`
+
+Requires Screenplay 4.183.0 or later (`screenplay --version`); older compilers use platform matching and may accept nonportable constructs.
+
+A quoted pattern is a flagless JavaScript expression restricted to a portable linear
+dialect, not arbitrary ECMAScript or .NET regex. It searches any substring unless
+anchored. Screenplay uses its own Thompson automaton, without timeout or host-engine
+settings. Syntax remains `matches "^INV-[0-9]{6}$"` or `matches email`.
+
+| Admitted | Meaning |
+| --- | --- |
+| Literals, `.`, `^`, `$`, alternation | `$` is strict end of input, not before a final newline |
+| `(…)`, `(?:…)`, `(?<name>…)` | ASCII names `[A-Za-z_][A-Za-z0-9_]*`; duplicate names only in disjoint alternatives; names that can match together report PLAY0367 |
+| Classes, negation, single-character ranges | Unions/complements use set semantics |
+| `\d \D \w \W \s \S` | `\d` is ASCII digits, `\w` ASCII letters/digits/underscore |
+| `\t \n \r \f \v`, `\0` not before a digit, `\xHH`, `\uHHHH` | UTF-16 code-unit escapes |
+| Escaped syntax characters and `\/` | `\-` also inside a class |
+| `* + ? {n} {n,} {n,m}` and lazy forms | No stacked quantifiers |
+
+`\s` includes U+00A0, U+FEFF and Unicode line/paragraph separators; it excludes
+U+0085. Dot excludes LF, CR, U+2028 and U+2029. `\w` excludes U+0130.
+`matches email` is conservative, not RFC 5322: one `@`, nonempty local part without
+whitespace/`@`, and at least two nonempty domain parts without whitespace/`@`.
+A no-break space therefore fails email validation. Other bare names report PLAY0366.
+
+PLAY0367 means invalid syntax, including stacked quantifiers. PLAY0699 means a
+construct outside the dialect: lookarounds, backreferences, word boundaries,
+Unicode properties, code-point escapes, control/octal/identity escapes, .NET-only
+anchors/options/class subtraction, empty classes, stray brackets, class escapes as
+range endpoints, or non-ASCII group names. Use explicit classes, UTF-16/hex escapes,
+`^`/`$`, or a literal text rule where equivalent. A length-only lookahead can become
+an anchored counted repeat; there is no general lookaround replacement.
+
+Limits are 1,000 decoded UTF-16 code units and 3,000 expanded nodes. Literals,
+classes, anchors and each optional/loop/alternative choice point count one. Counted
+repeats multiply their body by the upper bound (unbounded: lower bound plus one),
+adding optional/loop choices. `x{1500}` counts 1,500; `a{0,1500}` and `(a*){1500}`
+count 3,000. Exceeding either limit reports PLAY0699 before automaton construction.
+
+Older serialized ESM retains authored pattern bytes and loads, but invalid/refused
+patterns plan as UnsupportedValidation and generation checks report Unproven;
+re-authoring reports PLAY0367/PLAY0699.
+Browser matching remains advisory: JavaScript may backtrack even on admitted
+`(a+)+$`. The server-side linear check is authoritative.
+
+## Studio replacements and public check APIs
+
+Only exact escaped-literal Studio shapes desugar with warning PLAY0787, not PLAY0699:
+
+| Decoded pattern (`L` is an escaped literal) | Replacement |
+| --- | --- |
+| `^(?![\s\S]*L)` | `not contains "literal"` |
+| `L(?![\s\S])` | `ends with "literal"` |
+| `^L(?![\s\S])` | `== "literal"` |
+| `^(?!L$)` or `^(?!L(?![\s\S]))` | `!= "literal"` |
+
+Recognition requires a lossless escape/decode round trip: Studio v1 uses
+.NET Regex.Escape; v2 escapes `\ ^ $ . | ? * + ( ) [ ] { } /`. Other lookarounds
+remain refused. Plain `L`, `^L`, `^L$` and `L$` are unchanged. Syntax retains the
+original text, while binding stores the ordinal rule. Old ESM evaluates these exact
+patterns as replacements without changing bytes. The editor quick fix and MCP
+`propose-repair` migrate to literal rules preserving message/severity; preview the
+revision-bound canonical-formatting proposal before explicit apply.
+
+C#: `Cratis.Screenplay.Semantics.PortableMatchPattern.Check(pattern)`.
+TypeScript: import `checkPortableMatchPattern` from `@cratis/screenplay-compiler`.
+Both return PortableMatchCheck: status, code, construct, UTF-16 offset in the decoded
+pattern, suggestion, description and optional replacement `{ kind, value }`.
+Statuses are Admitted, Deprecated, Refused, Invalid (lowercase strings in TypeScript).
+Admitted has no code; Deprecated is PLAY0787, Refused PLAY0699, Invalid PLAY0367.
+Replacement kinds are Equal, NotEqual, Contains, NotContains, StartsWith, EndsWith.
+Checking never executes a pattern or constructs a platform regex.
+
+Validate with `screenplay <root> --warnaserror`, then execute acceptance/refusal
+examples through `screenplay test <root>`; source validation alone is not a rule test.