Stage.Contracts cannot express the Screenplay 2.x constructs, so they cannot survive a round trip

[woksin]

Summary

Cratis.Stage.Contracts is the intermediate representation the whole authoring pipeline passes through, and it is now narrower than the language it carries. Screenplay 2.x added constructs the contract cannot hold, so they are lost on import and unrenderable on output — no matter what the compiler, the importer or the renderer do.

The pipeline

.play → Screenplay compiler → Studio importer → Stage.Contracts.EventModel → Stage renderer → C#

Studio does not generate code itself: Source/Core/Program.cs:148 registers
Cratis.Stage.Rendering.Cratis.CratisRenderer.CreateDefault() as the IRenderer. Every construct has to
survive a round trip through EventModel in both directions.

What the contract cannot express

Source/Contracts/Slice.cs:

public record Slice(
    Guid Id, string Name, SliceType SliceType,
    IReadOnlyList<EventDefinition> Events,
    CommandDefinition? Command,        // one
    ReadModelDefinition? ReadModel,    // one
    IReadOnlyList<Specification> Specifications);

Missing entirely — no type in Source/Contracts mentions any of them:

Screenplay 2.x	Contract
readmodel <Name> standing alone	—
reducer <Name> => <ReadModel> with on rules	—
reads <ReadModel> [by <property>]	—
require <condition>	—
invokes <Command> on a reactor	—
scoped to <scope> on a query	—
for <expression> in a produces body	—
authorize	no authorization member on CommandDefinition

Two cardinality limits also now diverge: a slice may declare several commands and several
projections in Screenplay, and the contract holds one of each.

Why this is the gating item

Everything else in the chain is either done or mechanical:

• Screenplay 2.1.0 is released and expresses all of the above.
• Studio's importer already warns about what it drops (Cratis/Studio#1074) — it knows the gap exists.
• Stage's renderer can be extended once there is something to render from.

But a construct that cannot be held in EventModel cannot survive the round trip, so extending the
importer or the renderer first would have nowhere to put the data.

Suggested direction

Design the contract first, once, and let both sides encode against it. If the importer and the renderer
each grow their own understanding of a construct, they will disagree, and a round trip is exactly where
that surfaces — there is already one such asymmetry today: specifications and constraints are exported
by Studio but dropped on import (noted on Cratis/StudioIssues#52).

Worth deciding explicitly, as part of that design, which Screenplay constructs are deliberately not
carried to generated code. That is a product decision, and making it explicit is better than discovering
it as a silent drop later.

Sequencing

This is blocked behind a Cratis.Stage release built against Screenplay 2.x — 1.2.0 still bakes
Cratis.Screenplay.Secrets.ISecretsFiles into its generated convention-binding table, which throws
TypeLoadException on every AddCratisArcCore when Screenplay 2.x is on the graph. That release also
unblocks Cratis/Studio's absorption.

[woksin]

Correcting the premise before anyone builds against it

This issue says every construct has to survive a round trip through EventModel in both directions. That is true inbound and false outbound, and the difference decides what widening the contract can actually buy.

The renderer never sees an EventModel.

// Source/Contracts/Rendering/IRenderer.cs:22
Task Render(IReadOnlyList<ApplicationSyntax> applications, DirectoryInfo targetDirectory, TextWriter output, TextWriter error);

EventModel appears zero times in the source of Source/Rendering.Cratis (the only matches are obj/ and bin/ build artifacts). The single Cratis.Stage.Contracts reference in that project is CratisRenderer.cs:5, importing the IRenderer interface — which is typed on the Screenplay AST.

The real topology:

Arrow	Path	Contract on it?
Import	.play → ApplicationSyntax → ScreenplayEventModelVisitor → Contracts.EventModel → Studio canvas	yes
Render	Studio canvas → ToApplication() → ApplicationSyntax → CratisRenderer → C#	no
Run/spec	Studio canvas → ToStage() → Contracts.EventModel → Stage engine	yes

Confirmed on the Studio side: SliceCodeGenerator.cs:117 is await renderer.Render([pruned.Model.ToApplication()], …).

This issue cites Studio's Program.cs registering CratisRenderer.CreateDefault() as evidence the contract is on the render path. Registering it proves only that the renderer is the IRenderer — and IRenderer takes ApplicationSyntax.

Three consequences

1. Widening this contract cannot fix code generation. Not one line of rendered C# changes as a result. Render-side loss comes from Studio's ToApplication() fidelity and the renderer's own coverage of ApplicationSyntax — neither touches Contracts.
2. ApplicationSyntax needs no design work. It already expresses every 2.1 construct. The outbound encoding is done.
3. There is a third model this issue never mentions — Studio's own canvas EventModel. A construct must be holdable there to survive at all, and it is narrower than this contract. The contract is not the only bottleneck, and outbound it is not a bottleneck at all.

Proposed resolution: split this issue

As written it would spend a Stage major widening a contract that cannot improve generated code. Suggest closing it in favour of three:

• #23a — Import fidelity (Stage/Contracts). Widen EventModel so the canvas can receive 2.x constructs. Real, but only pays off once the canvas can hold them.
• #23b — Render coverage (Stage/Rendering.Cratis). Independent of this contract. Partly covered by Rendering silently drops authorize, queries and constraints #13 and Render stage to Chronicle #11.
• #23c — Studio canvas + ToApplication() fidelity. Not Stage's to fix.

#23a, concretely — and it needs no major

Screenplay already solved the binary-compatibility problem this issue assumes is unavoidable: trailing optional parameters plus init properties (SliceSyntax.ReadModels/Reducers, CommandSyntax.Reads, ProducesSyntax.For are trailing optionals; QuerySyntax.Scope is an init property specifically to avoid a binary break). Stage can copy that discipline, and then Tier 1 ships in a minor.

Tier 1 — additive, no design call:

Change	Shape
Command authorization	CommandDefinition(…, AuthorizationRequirement? Authorization = null) with a tree: PolicyReference(string) | LogicalRequirement(Left, And/Or, Right)
require	CommandDefinition(…, IReadOnlyList<Requirement> Requirements) — reuses the existing ProducedEventCondition tree
produces … for	ProducedEvent(…, ProducedEventProperty? For = null)
reads	CommandDefinition(…, IReadOnlyList<ReadsDefinition> Reads)
Spec read-model steps	Specification(…, GivenReadModels, ThenReadModels) — closes the orphaned SpecificationRunStepKind.ThenReadModel, which today is a step kind nothing can feed
Event tags	EventDefinition(…, IReadOnlyList<string> Tags)
Concept @pii / @sensitive	carry them — see below

Do not flatten authorization to string[]. That is exactly Screenplay #68, and a flat list cannot distinguish A or B and C from (A or B) and C. AuthorizeSyntax.References() already exists for consumers that only want the flat set.

Tier 2 — cardinality, genuinely breaking, one deliberate major, all together: Slice.Command → Commands, Slice.ReadModel → ReadModels, ReadModelDefinition.Projection → Projections. A migration that avoids even this: add the plural as trailing optionals, keep the singular as [Obsolete] computed accessors returning .FirstOrDefault(), flip at the next major.

Tier 3 — reducer and invokes. The contract change is easy; the engine has no reducer execution path and no command-invocation path. Sizing these as contract work would be wrong.

What should be declared out of scope, in writing

This issue asks for a product decision. Here is a proposed answer for the parts that should simply not be carried:

• scoped to and observable. The contract carries no query at all, the canvas has no representation, and the renderer emits a fixed IQueryable/ById pair regardless. Model queries properly or not at all — do not carry query modifiers onto a model that has no queries.
• screen, capture, seed, persona, authentication, layout. Whole families with no canvas representation and no renderer.

Sequencing, so the round trip is never half-widened

1. Studio canvas first (#23c) — a construct the canvas cannot hold gains nothing from a wider contract.
2. Contract Tier 1 (#23a) — additive, ships in a minor.
3. Studio importer consumes the new members.
4. Tier 2 cardinality as one deliberate major, all three together, never one at a time.
5. Renderer (#23b) independently, at any time.

One thing that should not wait for any of this

Concept @pii and @sensitive attributes are dropped on import. SchemaSynthesizer reads only IsEnum/Values/Type, so compliance markers do not survive a round trip. That is additive, Tier 1, cheap, and it is a compliance regression rather than a fidelity nicety. It appears in no issue today.

Also worth filing separately: readmodel and reducer are dropped by the renderer with no diagnostic at all — UnrenderedConstructs.Families() yields nine families and neither is among them, which contradicts that file's own stated contract that "a construct that renders to nothing and says nothing is indistinguishable from one that was never declared."