Declarative-first: the language must describe everything before code exists - 'file' must never be required

[woksin]

Principle

Screenplay's own workflow statement is author the document first, then Stage performs it. That only works if the language can describe everything before any code exists. A file <path> reference is realization metadata — a pointer attached once a slice has been implemented — and must never be the only way to give a construct meaning. Today the language mostly honors this, but not everywhere, and the exceptions break the authoring-first story.

Audit of where the language stands

Construct	Declarative story	file/code required?
command	produces (+ mappings, conditions)	No — handler is an optional escape hatch. OK
policy	require conditions	No — code block is an alternative. OK
screen	title, sections, tables, data, action, navigate, layout	No — file is an alternative. OK
constraint	unique … forms	Custom logic has only file — acceptable as an escape hatch, but see #32 for declarative predicates
reactor	None	Yes — every on trigger must carry a file or an inline code block; the parser rejects a trigger with no body.
projections	fully declarative (PDL)	No. OK
reducers / computed read models	none yet (#39)	— the constructs proposed in #39 must follow this principle too: file optional, not required

The reactor row is the defect. A greenfield author cannot write:

reactor AcceptedInvitationProvisioner
  on InvitationToJoinAdaAccepted

— "when an invitation is accepted, provision the account" — without first creating a code file to point at. The construct's meaning is locked inside the escape hatch.

Evidence from a generated document

A document generated from a real Arc application (Ada, via Cratis.Arc.Screenplay 20.65.0) contains 24 reactors, every one of the shape:

reactor AcceptedInvitationProvisioner
  on InvitationToJoinAdaAccepted
    file Admin/Invitations/Provision/Provision.cs

The file reference satisfies the parser and tells a reader nothing. This is not the generator's fault — the language offers no other way to state what a reactor does. (#34 proposes declaring reactor outputs — produces <Event> / executes <Command> — which is the missing declarative body.)

Suggested changes

1. Make reactor trigger bodies optional. A trigger with no body is a valid statement of intent ("this reactor observes this event"); a trigger with declared outputs (reactor: declare produced side effects (events and executed commands) #34) is a complete declarative description; file/code remains the realization escape hatch. At minimum allow description as a body while reactor: declare produced side effects (events and executed commands) #34 lands.
2. Treat file uniformly as attachable realization metadata on any construct that supports it, and state in the grammar documentation that a document must be expressible — and meaningful — with zero file references. Hand-authored documents precede code and gain file lines as slices are implemented; generated documents arrive with them pre-attached. Same language, two directions.
3. Apply the principle to new constructs by default — the reducer/computed-read-model constructs proposed in Read models without a declarative projection: reducers and computed views are undeclarable #39, the custom-constraint gap noted in Validation language: conditional rules, cross-property operands, and state-based business rules #32, and anything future: declarative meaning first, code pointer optional.

Context

Found while validating a generated 5,348-line document from a production Arc application: the constructs that lean on file are exactly the ones a reader cannot understand from the document alone. Related: #32, #34, #39.

[woksin]

Verified

Re-verified against main. The reactor row of your audit was the only one that failed: ReactorParser.ParseBody ended with

if (file is null && code is null)
{
    context.Error("Reactor trigger must have a 'file' directive or an inline code block", trigger.Location);
}

— even though ReactorTriggerSyntax already tolerated a body-less trigger. Every other construct in your table checked out: command has produces, policy has require, screen has its intent-level directives, and the PDL is fully declarative.

What landed

In #45 (open for review, not merged — it carries several language decisions together):

The requirement is gone. reactor X / on SomeEvent with nothing under it now compiles clean. grammar.md has a real ReactorTrigger production — the old one allowed exactly one trigger and required a body — and reactors.md gains a section on declaring the intent before the code exists.

The declarative body arrived with it (#34): repeated produces <Event> and executes <Command> under a trigger, resolved against the document's events and commands. So the three states you described are now all expressible:

reactor AcceptedInvitationProvisioner
  on InvitationToJoinAccepted                          # intent

reactor AcceptedInvitationProvisioner
  on InvitationToJoinAccepted
    produces UserAccountProvisioned                    # complete declarative description

reactor AcceptedInvitationProvisioner
  on InvitationToJoinAccepted
    produces UserAccountProvisioned
    file Admin/Invitations/Provision/Provision.cs      # realization attached

The principle is written down. reactors.md now states it as a general rule, not a reactor detail:

A document must be expressible and meaningful with zero file references. file is attachable realization metadata on any construct that supports it. Hand-authored documents precede the code and gain file lines as slices are implemented; generated documents arrive with them already attached. Same language, two directions.

The printer emits produces and executes above file, so the declarative description reads first and the pointer to code reads last.

Ratification

What I would like from you, @einari, is for this to be binding on future constructs, not just a paragraph about reactors — so it can be cited when the open issues are designed:

• Read models without a declarative projection: reducers and computed views are undeclarable #39 — reducer and readmodel. The observed events and the composed-over models must stand alone; file optional. Your alignment note on that issue already says this, and I have echoed it in my comment there.
• Validation language: conditional rules, cross-property operands, and state-based business rules #32 — custom constraint predicates, which today have only file. Same test: can a document state the invariant without pointing at code?
• command: declare read-model dependencies (DCB reads) and state-fed produces mappings #35 — reads <ReadModel>, which is declarative by construction, but the rules built on it must not fall back to validate csharp as the only expressible form.
• produces: express the target event source and multi-stream appends #33 — produces … for <key>. Here I think the principle has a limit worth naming: a derived stream identity computed by code (ICanProvideEventSourceId) is genuinely realization. The document should still say what is produced even when it cannot say where it lands — meaning the principle constrains the declarative parts to be sufficient for meaning, not for execution.

That last point is the one I would most like you to rule on, because it is where the principle could be read too strictly. My reading: a construct must be meaningful without file — a reader understands what it does and why it exists — but not necessarily complete without it. Under that reading a body-less reactor is fine, a produces without a computed target is fine, and only a construct whose purpose is invisible without code is a violation.

If you agree, I will cite this as settled when the remaining language issues are designed.