Screenplay extensions: systems, abilities and extension packages
A model often has to reach something it does not own: a carrier that books a pickup, a payment provider, a chat tool where someone approves a request. Screenplay keeps that reach declarative. The model says what the business can ask and what can come back. An extension is the code that does it, and it is chosen outside the model.
This page explains how the pieces fit and points to the page that owns each one. Start here when you think “I need Screenplay to talk to X” and follow the links.
The vocabulary
Section titled “The vocabulary”| Term | Meaning |
|---|---|
| System | A named external system the business can ask for something. See Systems and abilities. |
| Ability | One typed thing a system can be asked to do: inputs, optional returned values, named outcomes and an effect class. |
| Outcome | A named business result other than success, such as a refusal the external system gives. |
| Effect class | safe, idempotent or once: what a retry may do when an attempt’s result is unknown. |
| Extension | The realization of a system: the code and assets that carry its abilities out. |
| Extension package | The distributable unit of an extension. Its contract.play declares what it contributes. See Extension contracts. |
| Invocation | One durable request to perform an ability, with an identity of its own. |
| Activation | When an extension’s backend starts and stops. |
| Placeholder | The static HTML that design tools draw in place of an extension’s component. |
| Lock | screenplay.lock, which pins every extension reference to an exact release. |
The glossary holds one line for each.
One verb: invokes
Section titled “One verb: invokes”A reaction, a workflow action and a state’s entering line all ask a system for an ability with invokes <System>.<Ability>. The dotted name tells an ability from a command. Each input is mapped once, and the answer is handled where the call is made, with on returned, one branch per declared outcome and on failed. See Invoke an ability, and reactions, workflows and state machines for the places it appears.
invokes replaced the older sends in workflows, state machines and specifications. Operation phases that invoke an ability are covered in Operations and external systems. A command written in C# invokes abilities through Arc’s operations.
An invocation’s result is never turned into an event implicitly. The branch says which event records which outcome.
Code computes, abilities touch the world
Section titled “Code computes, abilities touch the world”Inline code that only computes may run anywhere and any number of times. Anything with an external effect goes through an ability, so it gets an identity, an idempotency key, retries, a recorded outcome and a place in specifications. This is the reason the effect class is part of the declaration, and once is the default: it is the only class that is never wrong. See Choose the effect class.
How an invocation runs
Section titled “How an invocation runs”Stage runs every ability invocation as a persisted message through Choreography, on the Orleans silo it already hosts. In short:
- The invocation is recorded with its cause before any work starts, so it is never held only in memory.
- One run handles the invocation, keyed by its identity, so asking twice does not call the system twice. The run pins the locked package digest, so upgrading an extension never changes an invocation in flight.
- Deployment limits on concurrent calls apply, then the extension is called.
- The outcome is recorded and handed back to the behavior that asked.
once abilities are never retried after an attempt that may have reached the system. They stop for reconciliation. An ability that answers later suspends its run until the answer arrives. The owning pages are Stage’s Durable ability invocations and Choreography’s answers that arrive later, capability gates and reconciliation.
Specifications script an ability’s answer without running anything. See Ability answers.
Packages, references, the lock and activation
Section titled “Packages, references, the lock and activation”A system that names a package declares no abilities of its own. The package’s contract.play provides them, so the contract and the model cannot drift.
system Payments extension "cratis/stripe" version 2 setting secretKey from secret StripeSecretKey activation on demand idle after 10 minutes- References. A reference is a catalog short name, a full OCI reference or an
npm:package for a frontend-only package. Without a version it means the latest release. See Referencing a package. - The lock.
screenplay.lockpins each reference to a version, a package digest, a contract hash and a publisher. Commit it. The compiler never resolves a range: it reads the contract by the locked digest from the vendoredextensionsfolder or the user cache. See The lock and the cache, vendoring and restore. - Naming is not trusting. Whether a package may run is decided by an allow-list of publishers in
.cratis/extensions.jsonand, for a deployment, by Stage. See the CLI’s trust rules and Stage’s Extension packages. - Settings and secrets. A system maps each setting its contract declares to a literal or a named secret, never a secret’s value. See System settings and named secrets.
- Activation and tiers. A backend runs in an execution tier and starts lazily. Reaching a screen that places the system’s components starts the backend. Mounting a component does not. See Stage’s Execution tiers and activation.
The extension, setting and activation lines are realization metadata. They change no bytes of the executable semantic model, so swapping one provider for another does not change what an invocation means.
What a package can contribute
Section titled “What a package can contribute”A contract can declare abilities, inbound triggers, settings, a backend and frontend components. A screen places a component with component <System>.<Component> <name>, names the system and never the package, and handles the signals the component raises. See Extension components and Interaction triggers. Inbound traffic such as a webhook is stored and acknowledged by Stage and delivered to the extension, which raises the contract’s triggers; see Stage’s inbound traffic and triggers.
An ability can also be realized without writing a backend, by the built-in http extension, which maps an ability to a REST call from a declarative block.
Where each part is documented
Section titled “Where each part is documented”| You want to | Read |
|---|---|
| Declare a system and its abilities | Systems and abilities |
| Invoke an ability from a behavior | Invoke an ability |
| Write a specification for an invocation | Ability answers |
| Understand the contract file, the manifest and the lock | Extension contracts |
| Configure settings, secrets and activation | Environments |
| Place an extension component on a screen | Extension components |
| Restore, update and vendor packages | cratis extension and Restore extensions |
| Run a model that uses extensions | cratis run |
| Create and verify a package | cratis extension new, cratis extension verify and the extension templates |
| Write a backend | Stage’s extension backends: protocol, host services and SDKs for C#, Kotlin, Go and TypeScript |
| Write a frontend component | Scene’s extension component contract and Build an extension component |
| Invoke abilities from a C# command | Arc operations that invoke abilities |
| Understand why it is designed this way | Decision 0159 and decision 0160 |
- Using an extension adds a package to a model and runs it.
- Building an extension creates, verifies and publishes one.