Cratis.Stage 3.9.2

<div align="center">

▶️ Cratis Stage

Compiles Screenplay source, verifies modeled specifications, and renders or partially performs Cratis applications.

</div>

Stage has three responsibilities around a Screenplay application:

1. Runtime — provide a disposable host that directly performs the subset of modeled backend behavior Stage currently understands.
2. Specification runner — verify the specifications declared in the model and write structured results.
3. 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.

Authoritative input

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.

Current scope

Renderer — highest priority

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.

Direct runtime — partial

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.

Specification runner — model-level verification

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.

Projects

Running the sandbox

Mount a folder containing one or more .play files:

docker run --rm \
    -p 9090:9090 \
    -p 35000:35000 \
    -v "$PWD":/eventmodel \
    cratis/stage:latest

The 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.

Running modeled specifications

docker run --rm \
    -v /path/to/screenplays:/model \
    -v /path/to/results:/output \
    cratis/stage-specrunner:latest

The 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.

Building

dotnet build -c Debug
dotnet test -c Debug
dotnet build -c Release

Release 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.

<div align="center">

Part of the Cratis platform · Licensed under the MIT license

</div>