Define and govern Screenplay portable executable semantics

[woksin]

Vision

Screenplay is the authoritative declarative and executable semantic model of an information system. People and AI author it, Studio visualizes it, specifications verify it, Stage executes it, and realization profiles render code and other artifacts.

This epic governs the boundary between portable model semantics and replaceable realization choices.

Scope

• Versioned executable semantic model with stable semantic identities.
• Portable execution plan and deterministic reference interpreter.
• Executable specifications and cross-backend conformance.
• Screenplay workspace, semantic snapshots, revisions, and typed patches.
• Semantic admission rules for future language work.
• Explicit capability requirements and fail-closed realization.
• Separation of model meaning from source provenance, framework realization, operations, and generated artifacts.

Admission rule

A capability belongs in Screenplay core only when it changes portable observable behavior, execution, specifications, Studio/AI reasoning, or equivalent generated backends; existing building blocks cannot already express it; and it has deterministic framework-neutral semantics.

Adapter diagnostics or framework API frequency alone do not justify syntax.

Explicit non-goals

Core Screenplay does not model HTTP routes, database CRUD APIs, message-broker dispatch modes, projection daemons, framework Saga classes, package versions, or deployment topology.

Children

Focused children cover:

• stable identities and executable semantic model;
• portable execution plan/reference interpreter;
• workspace and typed semantic patches;
• constrained embedded implementations;
• complete query and policy semantics;
• decision consistency;
• view-driven automation/business due time;
• affected-view identity/cardinality;
• data-subject relationships;
• portable event-contract evolution.

Acceptance criteria

• One serialized semantic model and specification corpus are canonical across file/folder forms.
• Stage and renderers consume the Screenplay-owned semantic model rather than competing partial models.
• Normalized Accepted/Rejected/Conflict/Unsupported outcomes are deterministic.
• Unsupported semantics block execution/rendering rather than being dropped or weakened.
• Studio and AI address stable semantic identities through revision-checked patches.
• Realization/provenance is deterministic and separate from semantic equality.
• The same conformance vectors pass in the reference interpreter, Stage, a Cratis-rendered target, and a materially different second target.
• Public syntax/compiler compatibility and canonical existing models remain protected throughout migration.

Architecture and delivery decisions are documented in SCREENPLAY_PLUS_ARCHITECTURE.md and SCREENPLAY_PLUS_PROGRAM.md.

[woksin]

Measured source-adapter evidence added since this issue was opened:

• MARTEN0011/MARTEN0012: exact authored persisted aliases, naming/schema-version helpers, and upcast registrations are retained, but current neutral/Screenplay contracts intentionally do not rename events or represent migration lineage.
• WOLVERINE0012: two exact receiver-bound event streams can retain separate Reads/Appends relationships and identity members, but one Screenplay state-change syntax cannot express both targets; neither command property is falsely marked as the sole identifier.
• WOLVERINE0013: exact persistence calls with opaque receiver/payload data fail closed instead of guessing an event or stream.
• Marten tenancy evidence (MARTEN0013) and bounded DCB evidence are active next increments. DCB tags/boundaries must not be represented as one stream append target.
• Saga-state return exclusion now prevents saga instances from becoming events/messages before full saga syntax exists.

Language-design implication: add syntax only after the neutral fact/disposition model is explicit. Highest-value measured candidates are now typed multi-target state changes/event boundaries, event alias/upcast metadata, validation application, tenancy, and saga/DCB workflow metadata. Preserve response/message/document/side-effect distinctions and use additive AST properties unless a deliberate major is chosen.

[woksin]

The measured language backlog is now split into independently releasable children: 129 130 131 132 133 134. Keep #128 as the evidence-driven epic; implement a child only against existing neutral facts and canonical loss diagnostics.

[woksin]

Architecture review reopened before any syntax work: Screenplay must remain a low-jargon human Event Modeling language, not a mirror of adapter/runtime metadata. We are testing every child #129-#134 against the existing Command/Event/View/Automation/Translation building blocks and official Event Modeling patterns. In particular, #133 is presumptively unnecessary: saga workflows appear expressible as events -> todo/read view -> automated trigger -> ordinary command -> events, with runtime saga state/correlation retained only as source provenance/diagnostics. No child will be implemented until this review produces a minimal, human-centered admission rubric.

[woksin]

Scope clarification from product direction: Screenplay is not merely human-readable documentation. It is the executable semantic source of truth for people, AI, Studio diagrams, Stage runtime/model execution, specifications, and generation of code as a replaceable artifact in multiple frameworks. The active review therefore distinguishes (1) portable executable semantics that every backend must realize, (2) human/AI presentation, (3) framework realization profiles, and (4) operational provenance. Technical terms stay out of the core only when they are realization choices; semantics required for deterministic execution, testing, visualization, or backend conformance must remain representable in a framework-neutral form.

[woksin]

Screenplay++ focused children created after cross-repository research:

• Define stable semantic identities and the executable semantic model #135 stable semantic IDs and ESM
• Build a portable execution plan and deterministic reference interpreter #136 portable execution plan/reference interpreter
• Provide a loss-preserving Screenplay workspace for file and folder editing #137 loss-preserving workspace
• Apply revision-checked semantic patches to Screenplay models #138 revision-checked semantic patches
• Define constrained implementation bodies and embedded-language services #139 constrained implementation bodies/language services
• Complete portable query selection, ordering, paging and specifications #140 complete portable queries
• Relate personal-data values to their data subject #141 data-subject relationships
• Define portable policy evaluation and authorization specifications #142 portable policies

Existing rewritten children: #129 decision consistency, #69 view-driven automation/business due time, #132 affected-view identity, #71 event evolution, #73 external occurrence responsibility, #87 executable specifications. Closed technical framings: #130, #131, #133, #134.

[woksin]

Release-line audit against the 2026-08-06 vision:

• Preserve and deepen the genuine language core: concepts/types, modules/features/slices, commands/events, read models, PDL/CDL, reactions, policies, queries, and Given/When/Then specifications.
• Do not expand realization-shaped vocabulary (file, handlers/performers, framework concurrency/topology, transport details, detailed UI/package/layout mechanics) as portable semantics. Classify it through Define stable semantic identities and the executable semantic model #135 as legacy, report-only, migrate, block, or explicitly deferred.
• Existing focused owners remain Make Screenplay specifications portable and executable #87 (executable specifications), Define constrained implementation bodies and embedded-language services #139 (constrained implementation bodies), Complete portable query selection, ordering, paging and specifications #140 (portable queries), Define portable policy evaluation and authorization specifications #142 (policies), Model view-driven automation and business due time #69 (business due-time automation), Define portable event-contract identity and evolution #71 (event evolution), and Declare which read-model instances an occurrence affects #132 (affected-view identity). No duplicate capability issues are needed.
• Keep the language reference and grammar release-complete #146 now owns release-complete language documentation and grammar conformance, including accurate public claims and compiling examples.

Direction: make the ESM the runtime-neutral semantic authority, keep PDL/CDL bounded and independently consumable, and move toward the smallest executable backend vertical before adding more syntax.

[woksin]

Cross-repository execution order

Active checkpoints

• Screenplay PR Add query result assertions to specifications #150 — authored query-result specifications (Make Screenplay specifications portable and executable #87)
• Screenplay PR Define constrained implementation attachment boundaries #151 — constrained implementation/AI architecture checkpoint (Define constrained implementation bodies and embedded-language services #139/Prove bidirectional semantic fidelity between Screenplay and code #148)

First deterministic rendering milestone

1. Screenplay Define stable semantic identities and the executable semantic model #135 — ApplicationSyntax -> ESM binder and complete disposition matrix.
2. Screenplay Build a portable execution plan and deterministic reference interpreter #136 — minimum execution plan/reference evaluator and RegisterProject vectors.
3. Release the Screenplay kernel package.
4. Stage Align the invoicing sample and projection docs with the language definitions #23/Expand the language: types, identifiers, contexts, performers and declarative-first reactors #56 — consume ESM through pure ArtifactRenderPlan; render the declarative Cratis vertical and generated specifications.
5. Release Stage planner/Cratis target packages.
6. CLI Add theme language construct #101 — safe root cratis render, manifest, journal, user-file protection, deterministic recovery.

First implementation-attachment pilot

7. Screenplay Define constrained implementation bodies and embedded-language services #139 — common requirement/attachment envelope plus one query-performer role and virtual-document contract.
8. Stage Expand the language: types, identifiers, contexts, performers and declarative-first reactors #56 — Cratis query-performer provider; unresolved attachment is a blocking non-publishable gap.
9. Screenplay Prove bidirectional semantic fidelity between Screenplay and code #148 + Generation Add a fully auto-mapped projection to the invoicing sample #24 + CritterStack Resolve reserved directive keywords colliding with property names #44 — render -> recover requirement/attachment identity and semantic conformance.
10. Add AI candidate generation only after the manual attachment flow passes compilation and Screenplay specifications. StudioIssues #261 owns review/acceptance; CLI may later expose explicit headless orchestration.
11. Prove a TypeScript/Node provider before expanding to further implementation roles.

Repository boundaries

• Screenplay owns semantics, requirements, specifications, attachment/candidate contracts, and language tooling.
• Stage owns runtime providers, pure planning, and renderer target integrations.
• CLI owns selection and safe publication, never semantic or AI decisions.
• Generation/CritterStack/Arc own source evidence and framework-specific recovery.
• Studio owns candidate review/acceptance. Scene/frontend and deployment remain deferred.

Use one branch/worktree and one draft PR per repository increment. Release upstream packages before updating downstream dependencies; keep exact issue/PR links and conformance evidence on the owning issues.

[woksin]

Fresh-session handover now prioritizes two concrete end-to-end proofs: (1) Screenplay → generated buildable Cratis application/specifications through active Stage PR #60; (2) existing Cratis code → CritterStack/Generation → Screenplay → visible Studio model/view. The generated application remains the immediate priority; the Studio recovery view follows as the first bidirectional product proof.

[cratis-direct]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.

[woksin]

A concrete portable-semantics gap from the released RegisterProject rendering proof is now tracked in #167. It owns event destination/event-source context separately from event payload, without importing Chronicle topology into core. Treat #167 as a hard acceptance dependency for the final narrow Cratis conformance vector, not as adapter evidence or a generated-code convention.

[woksin]

Reconciled end-to-end execution order after Generation 0.17

The program now runs as two joined tracks around Screenplay semantic authority:

Studio or .play -> workspace/ESM -> Stage plan -> CLI publication -> buildable Cratis/specs
Cratis source -> Generation/Arc/Critter evidence -> reviewed candidate -> revision patch -> Studio

Immediate parallel cells are now active in clean isolated worktrees:

1. Provide a loss-preserving Screenplay workspace for file and folder editing #137 workspace — exact source bytes/trivia/document ownership, persisted IDs, canonical ESM projection, expected-revision transactions and pure write plans.
2. Separate event destination identity from event payload and expose event-source context #167 event destination/context — remove stream identity from event payload, expose typed event context to projections/specifications, and correct the RegisterProject vector.
3. Generation Add a fully auto-mapped projection to the invoicing sample #24 — deterministic realization/provenance report over frozen runs/derivation; explicitly separate from Generation @pii: carry the reason/lawful-basis documentation, not just the marker #38 external evidence.
4. CritterStack Resolve reserved directive keywords colliding with property names #44 — atomic Marten/Wolverine/integration adapters with compatibility-facade byte/API parity, then CLI Language construct: layout arrangement — responsive flow vs. freeform #95 profiles.

Before any implementation PR, these lanes reconcile identity domains: #137 persisted semantic catalog, #167 destination/context identity, #24 report links, and #44 project-qualified source subjects. Source, Studio GUID/layout, generated artifacts and runtime IDs remain non-authoritative.

After the first releases: #138 + StudioIssues #101/#52/#260/#261 make Studio a transactional projection over the same workspace and Stage plan; Prologue #18/#22 provides reviewed reverse patches; #139/#140/#142 plus Stage/Arc providers complete implementation handoffs, queries and policies; a materially different Node backend is required before #148/#128 close.

Completion gates remain fail-closed: no legacy renderer fallback, no TODO/default stubs, no partial writes, exact file/folder/Studio semantic parity, generated Debug/spec/Release success, target-matched render->recover IDs/outcomes, and no Required/Blocked capability-ledger cells.

[woksin]

Work has started locally as part of the coordinated end-to-end Screenplay/Stage/Studio/CLI delivery effort tracked in #174. @woksin is coordinating implementation in dependency order with repository-specific AI corpus instructions and specifications. Existing work/PRs will be reconciled rather than duplicated. This is a kickoff, not a completion claim; focused progress, verification evidence and blockers will follow here.

[woksin]

Status after v4.20.0 (triage of what shipped in v4.18.0–v4.20.0):

The in-repo half is done: one canonical serialized model with a corpus across file/folder forms, normalized Accepted/Rejected/Conflict/Unsupported outcomes (Semantics/Execution/SemanticExecutionContracts.cs:11-31,42,94), fail-closed blocking on unsupported semantics, stable semantic IDs with revision-checked patches, and compatibility specs.
Remaining criteria are cross-repo conformance (Stage/CLI/Generation consuming this model, and a materially different second target) plus governance — not code in this repository.
Housekeeping: the body cites SCREENPLAY_PLUS_ARCHITECTURE.md / SCREENPLAY_PLUS_PROGRAM.md, which are not tracked in this repo (nearest are untracked local .ai-work/ files). Those references should be replaced or the content landed as a decision record.