Compiles Screenplay source, verifies modeled specifications, and renders or partially performs Cratis applications.
Stage has three responsibilities around a Screenplay application:
- Runtime — provide a disposable host that directly performs the subset of modeled backend behavior Stage currently understands.
- Specification runner — verify the specifications declared in the model and write structured results.
- Renderer — turn compiled Screenplay syntax into a reviewable Cratis Arc + Chronicle application on disk.
The renderer is the project's highest-priority path. Direct runtime execution and specification verification are useful, but partial; they must not be read as proof that every Screenplay construct has executable semantics. Frontend and UI rendering are deferred.
Stage is part of the experimental Cratis model-first layer: Screenplay is the modeling language, Studio the collaborative modeling environment, Scene the platform-neutral UI model, and Prologue captures existing system behavior into event models. What Stage renders is an event-sourced CQRS application built on Cratis Arc and Chronicle, the Cratis event-sourcing database and runtime.
The authoritative input is Screenplay source: a .play file or a folder containing .play files. The host and
specification runner recursively compile every .play file beneath the folder they receive and merge the
results. Stage's contract models are internal/tooling seams produced from that compilation; an
event-model.json file is not the current startup or rendering contract.
flowchart LR
Play[["📄 Screenplay<br/>*.play files"]]
Play -->|compile| Runtime["▶️ partial runtime<br/>Arc + Chronicle API"]
Play -->|compile| Specs["🧪 model specification runner<br/>results.json"]
Play -->|compile| Renderer["🎨 Cratis renderer<br/>C# application source"]
Stage is independent of Studio. Studio, the Cratis CLI, and other tooling can supply the same Screenplay source without Stage depending on any one authoring environment.
Cratis.Stage.Rendering.Cratis exposes a pure executable-semantic-model planner. It accepts an immutable
ArtifactRenderRequest and returns a complete in-memory ArtifactRenderPlan with normalized paths, exact bytes,
SHA-256 hashes, and typed diagnostics before publication. The currently admitted vertical includes concepts,
composite types, one command/event production path, one-instance projection state, an optional snapshot lookup,
and modeled specifications. Unsupported reachable semantics block publication instead of producing thinner code.
Cratis CLI publishes successful plans through its managed artifact publisher.
The published syntax-based IRenderer remains available as a compatibility path for the older, broader syntax
surface. That path writes directly and has no managed staging or safe stale-file removal. A failure can leave its
target unsafe and incomplete; render legacy output into a fresh target and review it before building or running.
Do not use that direct-write compatibility path as the basis for a new target.
Other model limitations are reported as render diagnostics. Cratis.Stage.Rendering.Cratis.Scaffolding can place
output into a project created from Cratis templates. Rendering currently targets backend applications. Screens,
layouts, forms, components, and other frontend/UI output are not rendered yet.
The cratis/stage image is a disposable sandbox containing the Stage host and an in-memory Chronicle kernel. It
loads a folder of .play files and exposes the runtime surfaces Stage currently implements. This path is not a
complete executable implementation of the Screenplay language and should not be treated as a generated
production application.
Runtime commands evaluate their modeled produces mappings, append the resulting facts to Chronicle, and echo
the payload as the response. Modeled command validation and authorization are not yet enforced by this runtime
path.
Stage also does not yet receive an executable query authorization contract. Modeled query performers deny access by default and return no data, so they cannot expose projected documents while authorization semantics are absent. Full query authorization and query execution are blocked on the Screenplay-owned executable semantic/query model; Stage does not invent an interim query DTO contract.
cratis/stage-specrunner is a run-to-completion job. It compiles the .play files, checks the modeled
specifications against the model, writes results.json, and exits. Verification is currently model-level: it
checks the modeled facts and expectations but is not a substitute for behaviorally executing every slice against
a live runtime.
| Project | Package / image | Purpose |
|---|---|---|
Source/Contracts |
Cratis.Stage.Contracts |
Contract models and converters produced from compiled Screenplay syntax, specification results, and Scene/render-plan contracts used by Stage tooling. |
Source/Rendering.Cratis |
Cratis.Stage.Rendering.Cratis |
Cratis-specific backend renderer with method-specific query authorization and explicit failed-operation signaling; direct-write targets remain unsafe after failure. |
Source/Rendering.Cratis.Scaffolding |
Cratis.Stage.Rendering.Cratis.Scaffolding |
Optional Cratis template scaffolding around rendered source. |
Source/Stage |
Cratis.Stage |
Partial direct runtime engine: dynamic API types, command handling, Chronicle registration, specification strategies, and fail-closed modeled query performers. |
Source/Host |
cratis/stage |
Disposable HTTP host paired with an in-memory Chronicle kernel for direct runtime exploration. |
Source/SpecRunner |
cratis/stage-specrunner |
Container job for model-level specification verification and results.json output. |
Mount a folder containing one or more .play files:
docker run --rm \
-p 9090:9090 \
-p 35000:35000 \
-v "$PWD":/eventmodel \
cratis/stage:latestThe Stage API is exposed on port 9090; the Chronicle Workbench is exposed on port 35000. The host takes the
model folder as its first argument. Deployment configuration is read from cratis-stage.json, with its path
overridable through STAGE_CONFIG.
docker run --rm \
-v /path/to/screenplays:/model \
-v /path/to/results:/output \
cratis/stage-specrunner:latestThe runner accepts --model <folder> and --output <file>, with optional --slice <guid> and --spec <guid>
filters. The container defaults to /model and /output/results.json.
Full container, URL, specification-result, and render-plan documentation lives in Documentation. Framework maintainers can use the renderer target guide to implement another deterministic Screenplay-to-code target.
dotnet build -c Debug
dotnet test -c Debug
dotnet build -c ReleaseRelease treats warnings as errors. Both Dockerfiles consume prebuilt, framework-dependent publish output;
./dockerize.sh publishes the host and specification runner and then builds both images.
This project is part of Cratis — free, MIT-licensed tools for building event-sourced and CQRS applications.
- Chronicle — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. Docs
- Chronicle clients — first-class .NET SDK, plus TypeScript, Kotlin/Java, and Elixir; Python coming soon (pre-alpha). AI agents connect through the Chronicle MCP server.
- Arc — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. Docs
- Components — React components aligned with Arc patterns. Docs
- CLI + Workbench — inspect and diagnose Chronicle from the terminal or the browser. Docs
- Model-first layer (experimental) — Studio, Screenplay, Stage (this repository), Scene, Prologue
- Supporting — Fundamentals, Specifications, Synopsis, Lens, Narrator, and free AI tooling (preview); Ensemble coming soon (pre-release)
- Samples — runnable event sourcing and CQRS samples for the whole stack
Everything Cratis publishes today is MIT licensed and free to use.
Part of the Cratis platform · Licensed under the MIT license