Screenplay systems and abilities: declare what an external system can be asked
A model often has to reach something outside itself: a carrier that books a pickup, a ledger that opens a cost center, a chat tool that asks someone to approve. A system names that business system. An ability says one thing the system can be asked to do, with typed inputs, the values it returns, the business outcomes other than success, and what a retry may do. With abilities declared, invocations of the system can be checked, specified and run.
This page covers the declaration. A reaction, a workflow action or a state’s entering line invokes an ability; see Invoke an ability.
Declare a system with abilities
Section titled “Declare a system with abilities”concept ParcelId : Uuidconcept TrackingNumber : String
type Address street String postalCode String
system Carrier description "The parcel carrier's booking service" ability BookPickup idempotent description "Books a pickup for one parcel" parcelId ParcelId address Address returns trackingNumber TrackingNumber pickupAt DateTime outcome NoCapacity description "No pickup slot on the requested day" ability CancelPickup idempotent trackingNumber TrackingNumber ability Quote safe address Address returns price DecimalA system belongs to the application, including when its file is imported into a module or feature. It names the business system, not a provider interface: the model says what the business can ask, and an extension or an implementation owns how.
Each ability line names the ability and, optionally, its effect class. Everything under it is optional and may appear in any order; the canonical printer writes them in the order of this page.
| Line | Meaning |
|---|---|
description "..." |
What the ability does, for readers and tools. |
<input> <Type> |
A typed input. |
returns |
A block of typed fields the ability gives back. An ability without returns returns nothing. |
outcome <Name> |
A named business result other than success, such as a refusal the external system gives. |
answers later |
The answer arrives after the invocation returns. |
implementation, file, a tagged fence |
The code that carries the ability out. |
Choose the effect class
Section titled “Choose the effect class”The effect class says what a retry may do when the outcome of an attempt is unknown. Write it after the name: ability BookPickup idempotent.
| Class | Meaning | When an attempt’s outcome is unknown |
|---|---|---|
safe |
No external effect, such as a lookup. | Retry freely. |
idempotent |
Repeating with the same idempotency key has the effect once. | Retry with the same key. |
once |
Repeating may repeat the effect, as when posting a message without deduplication. | Never retry; stop for reconciliation. |
once is the default, because it is the only class that is never wrong. You opt into retries by saying the system can take them. An effect class other than safe, idempotent or once is PLAY0984.
Inputs and returned values
Section titled “Inputs and returned values”Inputs use the same property grammar as operation inputs: concepts, enums, composite types, collections and optional. They cannot be identifier or generated, and they carry no subject modifier. An input named like a keyword (description, outcome, implementation or file) is written with an @ prefix, such as @outcome String.
returns holds typed fields in the same form, one per line, and needs at least one. Every type, in inputs and in returns, must be declared: a concept, a type, an enum or an import. An unknown type is PLAY0986.
Name the outcomes
Section titled “Name the outcomes”An outcome is a business result the external system can give instead of success. It is the external counterpart of a command refusal. An outcome has a name and an optional description. It carries no payload in this version.
system Warehouse ability Reserve idempotent sku String quantity Int outcome OutOfStock description "Not enough stock to cover the quantity" outcome DiscontinuedAn outcome cannot be named next, refused, failed, returned or expired, compared ignoring case, because those are outlets that invocation sites use (PLAY0985). Outcome names are unique within an ability.
Answers that arrive later
Section titled “Answers that arrive later”Some systems answer after the call returns: a person approves in a chat tool, or a partner confirms by webhook. Mark such an ability with answers later:
concept ParcelId : Uuid
system Approvals ability RequestApproval once answers later parcelId ParcelId outcome DeclinedWorkflows and approval ... via use these abilities; see Invoke an ability.
Attach an implementation
Section titled “Attach an implementation”An ability may carry the code that carries it out. Use the same wrapper that operation phases use: a file, a tagged fence, or an implementation block with ordered hint lines and an optional source.
concept ProjectId : Uuidconcept CostCenterCode : String
system Ledger description "The finance department's ledger" ability OpenCostCenter idempotent projectId ProjectId returns costCenter CostCenterCode implementation hint "Use the existing accounting adapter" file Adapters/OpenCostCenter.csAn ability owns at most one file or tagged fence, directly or inside its implementation wrapper. Combining sources is PLAY0494. This is the AbilityEffect attachment role of the implementation envelope. Its result is exactly one of: values matching returns, a declared outcome, or a failure. A missing or mixed result is never success.
A hints-only block is intent. It leaves the ability unrealized.
Names and diagnostics
Section titled “Names and diagnostics”Ability names are unique within their system, compared ignoring case (PLAY0983). A malformed ability, an outcome with a payload, an empty returns block, an identifier input or a repeated answers later is PLAY0495. The codes are listed in the diagnostics reference.
What reaches the executable model
Section titled “What reaches the executable model”A model that declares at least one ability selects executable semantic model (ESM) v50. Models without abilities keep their bytes and their version. In ESM v50 and later, application.systems lists each system and its abilities:
| Member | Meaning |
|---|---|
systems[].id, name |
The system’s stable identity and name. |
abilities[].name |
The ability name. |
abilities[].effect |
safe, idempotent or once; the default is written out as once. |
abilities[].inputs |
Typed inputs, { name, type }, in declaration order. |
abilities[].returns |
Typed returned fields, omitted when there are none. |
abilities[].outcomes |
Outcome names, ordered by name. |
abilities[].answersLater |
Whether the answer arrives after the invocation returns. |
abilities[].realization |
{ kind: none | code | extension, requirementId? }. code carries the AbilityEffect implementation requirement. |
Descriptions are authoring metadata and stay out of the model. Which extension package, version, setting or activation realizes a system does not change what an invocation means, so it is realization metadata, not part of the ESM bytes. The extension, setting and activation lines are described in Environments.
The executable model schema and the published ESM v50 schema describe the JSON.
A system declared in a model that declares no ability anywhere, operations, and operation specification steps remain authoring-only: binding reports PLAY0268.
Invoke an ability
Section titled “Invoke an ability”A reaction, a workflow action and a state’s entering line ask a system for an ability with invokes <System>.<Ability>. The dotted name is what tells an ability from a command. Each input the ability declares is given a value, and the ability’s answer is handled where the call is made.
reaction PickupBooking runs as system when OrderPacked parcelId shippingAddress invokes Carrier.BookPickup parcelId = parcelId address = shippingAddress on returned produces PickupBooked trackingNumber = $result.trackingNumber on NoCapacity produces PickupUnavailable on failed produces PickupBookingFailed reason = $failure.reason- Every declared input is mapped exactly once, with a value of a compatible type (
PLAY1003,PLAY1004,PLAY1005). The system and ability must exist (PLAY1001). on returnedhandles a normal answer and reads$result.<field>from the ability’sreturns.on failedhandles a failed call and reads$failure.reason.on <Outcome>handles one of the ability’s declared outcomes (PLAY1002). A branch is declared once (PLAY1006), and a branch value read outside its branch isPLAY1008.- A
onceability is never retried, soattemptsabove one on its call site is the warningPLAY1015. A reaction has no place to wait, so an ability thatanswers latercannot be invoked from one (PLAY1010). - Specifications script the answer with
given <System>.<Ability> returns,answersorfailsand assert the call withthen invokes; see Specifications.
Reactions, workflow actions and state entries that invoke an ability select executable semantic model (ESM) v51. Models that invoke no ability keep their bytes and their version. Operation phases that invoke an ability, an approval answered through an ability (via), a compute node, a $trigger value and a decide that reads an ability or compute result parse, print and validate but are not admitted yet; binding reports PLAY0268 naming #1252.
Cratis Stage lists which ESM features it renders and runs. The design is decision 0159.
Related
Section titled “Related”- Operations and external systems describes slice-owned operation intent that uses a system.
- Reactions, workflows and state machines are where invocations belong.
- Extension contracts is the reference for the contract file, the
extensionreference, the lock and restore. - Environments covers extension settings, named secrets and activation.
- Grammar holds the productions.