@cratis/pi 7.79.0 → 7.80.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -171,9 +171,9 @@
171
171
  }
172
172
  ],
173
173
  "synced": {
174
- "version": "4.212.4",
175
- "date": "2026-10-17",
176
- "by": "Cratis/AI#772"
174
+ "version": "4.213.0",
175
+ "date": "2026-10-18",
176
+ "by": "Cratis/AI#771"
177
177
  },
178
178
  "covers": {
179
179
  "skills": [
@@ -201,7 +201,7 @@
201
201
  ],
202
202
  "rules": []
203
203
  },
204
- "notes": "Cratis/AI#772: standalone Screenplay 4.212.4 pinned; regenerated compiler contract is byte-identical to the v4.212.4 release asset. Source-checked joined-event automap/no automap overrides and level fallback in executable binding; PLAY0380 covers only all inside children/nested. No new render/runtime probe. Prior: Cratis/AI#769: standalone Screenplay 4.212.3 pinned; regenerated compiler contract is byte-identical to the v4.212.3 release asset. Source-checked both compilers and projection documentation for PLAY0801 DuplicateEventInProjectionScope: shared from/removal/clear set, separate join set, fresh sets per children/nested/variant level, and no two-row update through repeated from blocks with different keys. No new render/runtime probe. Prior: Cratis/AI#768: standalone Screenplay 4.212.2 pinned; regenerated compiler contract is byte-identical to the v4.212.2 release asset (unchanged from the previous contract). Source-checked v4.212.0 split-model dotted note targets, open-workspace applicationIdentity and complete add/reanchor substitutions; unbound container identities are not claimed. v4.212.1 aligns PLAY0535 collection fields, optional parameters and single-result identity inference. v4.212.2 counts read-only query denials for SPEC004, not SPEC006. No new render/runtime probe. Prior: Cratis/AI#762 and #761: source-checked v4.210.0 and v4.211.0 contracts for PLAY0800 CommandHandlerRequiresAttachment (required typed subject, permanent code-attachment requirement, other PLAY0268 families unchanged), independent reference remove/add batches, located same-text ambiguity conflicts and string MCP conflict/move-report document fields. v4.211.1 mapping changes inspected but excluded from this guidance update at the user's request; no typed PLAY0273 property/type arguments are claimed. Standalone Screenplay 4.211.1 and its compiler contract pinned; the contract is a byte-identical copy of the v4.211.1 release asset. No new render/runtime probe. Prior: Standalone 4.205.0 and byte-identical compiler contract pinned. Cratis/AI#746: Uuid ==/!= in command require and produces when (ESM v28): same-concept rule, bare Uuid against a concept, canonical literals, protected read paths in require only; PLAY0268 (different concepts, ordering, Uuid validation and concept rules, read paths in produces when) and PLAY0273 (non-canonical literal) checked against the 4.205.0 compiler, v28 selection read from the MCP executable-model view; Stage admits exact v1-v21 and v23-v26 pairs so v28 is refused STAGE-ESM-016, not probed against a Stage image; CLI 3.74.0 renders through v26. Prior: Standalone 4.204.0 and byte-identical compiler contract pinned. Cratis/AI#702 and #691: PLAY0690 reducer identity (Screenplay 4.170.0, native compiler only) and the screenplay.json validation gate (Screenplay 4.165.0; cratis screenplay validate reads it from CLI 3.65.0) are taught and probed against the 4.204.0 compiler. Cratis/AI#743: flat composite read-model keys (ESM v27): untyped projection key blocks on root from and remove with, equality-filter lists, single-instance by blocks and per-part fixtures, with PLAY0661/PLAY0662/PLAY0268 refusals checked against the 4.204.0 compiler; Stage origin/main still refuses v27 with STAGE-ESM-016 (stage-rendering.md); Stage v4.135.0 v26 admission (Host and executor run date comparisons; renderer STAGE-ESM-046) was source-checked for this sync; no render or runtime probe. Prior: Standalone 4.201.0 and byte-identical compiler contract pinned. Cratis/AI#733: the ui profile root template, shell options, appearance and new screens default (PLAY0788-PLAY0799, quick fix for the legacy layout line, ui-profiles MCP tool, 44 tools). Cratis/AI#735: chronological Date/DateTime ordering in command conditions and command/property literal validation (ESM v26), UTC tick precision and pre-rule offset validation; then matching remains ordinal. Source-checked Screenplay v4.199.0 commands, diagnostics, interoperability and specifications documentation plus decision 0087. Stage v4.127.1 still refuses v26 with STAGE-ESM-016 (stage-rendering.md and SemanticVersionFeatures.Supports); no render/runtime probe. Cratis/AI#576: prior mechanical compiler catch-up. Language batch #717/#722/#723/#724/#720/#728/#734 teaches atomic reaction batches (v22), described payload handlers (v23), portable linear matching, ordinal text rules (v24), protected command reads (v25), diagnostic arguments and event-source invokes mappings. Facts read at Screenplay v4.198.0 and introducing tags; Stage v4.127.0 admits exact v1-v21 and v23-v25 pairs but refuses v22/v26 and mixed pairs (STAGE-ESM-016), protected reads (044), atomic mode (043) and described handlers (STAGE-IMPL-002), even Stub mode. Stage text rules execute/render; no new renderer/runtime probe or Stage pin uplift. Cratis/AI#706: application navigation regions (module inherit, extend or override), toolbar slice buttons, blueprint template references and sample data packs in cratis-screenplay-ui-composition (references/application-shell.md), with the canonical shell vector and the rejection codes PLAY0710-PLAY0722 and PLAY0740-PLAY0765. Examples moved to the executable-state rules since 4.164: translator reactions in an Automation slice beside the Translate slice (PLAY0694) and the first record of a capture key appended with `when added`. Earlier: Standalone 4.164.0 and byte-identical compiler contract pinned. Cratis/AI#663: one origin per capture (PLAY0687). #668: executable no-event/redelivery v17. #684: concept query-argument validation in every version and query-error assertions v18. #681: executable refusal branches and refusal values v19. #666: proposal summary/severity counts and exact structural source proposals. Generated-concept rules select v20 with PLAY0688/0689 proofs and derived-matches repair; generated secrets and preview strategies remain refused. Release-baseline from-esm admission reads storedName. Standalone binding is not renderer admission: Stage 4.103.0 admits v1-v17 and v19; CLI 3.62.0 bundles Screenplay 4.159.0 / Stage 4.99.0 and renders through v16. Prior evidence remains unless superseded; no new renderer, Docker or browser probe."
204
+ "notes": "Cratis/AI#771: standalone Screenplay 4.213.0 pinned; regenerated compiler contract is byte-identical to the v4.213.0 release asset and unchanged from 4.212.4. Reviewed the full v4.212.4-v4.213.0 delta against tagged decision 0093 and MCP reference: pre-binding container identities and stable binding/migration continuity, own-slice member substitutions, containerIdentities completeness/ambiguity/collision refusals, retained ambiguous notes, explicit semanticRenames/retirements, binding fixes through MCP, exact reopen exception, notes/identity rollback and exact-ID re-add anchoring. No grammar, binder, ESM or diagnostic-code changes; no new render/runtime probe. Prior: Cratis/AI#772: standalone Screenplay 4.212.4 pinned; regenerated compiler contract is byte-identical to the v4.212.4 release asset. Source-checked joined-event automap/no automap overrides and level fallback in executable binding; PLAY0380 covers only all inside children/nested. No new render/runtime probe. Prior: Cratis/AI#769: standalone Screenplay 4.212.3 pinned; regenerated compiler contract is byte-identical to the v4.212.3 release asset. Source-checked both compilers and projection documentation for PLAY0801 DuplicateEventInProjectionScope: shared from/removal/clear set, separate join set, fresh sets per children/nested/variant level, and no two-row update through repeated from blocks with different keys. No new render/runtime probe. Prior: Cratis/AI#768: standalone Screenplay 4.212.2 pinned; regenerated compiler contract is byte-identical to the v4.212.2 release asset (unchanged from the previous contract). Source-checked v4.212.0 split-model dotted note targets, open-workspace applicationIdentity and complete add/reanchor substitutions; unbound container identities are not claimed. v4.212.1 aligns PLAY0535 collection fields, optional parameters and single-result identity inference. v4.212.2 counts read-only query denials for SPEC004, not SPEC006. No new render/runtime probe. Prior: Cratis/AI#762 and #761: source-checked v4.210.0 and v4.211.0 contracts for PLAY0800 CommandHandlerRequiresAttachment (required typed subject, permanent code-attachment requirement, other PLAY0268 families unchanged), independent reference remove/add batches, located same-text ambiguity conflicts and string MCP conflict/move-report document fields. v4.211.1 mapping changes inspected but excluded from this guidance update at the user's request; no typed PLAY0273 property/type arguments are claimed. Standalone Screenplay 4.211.1 and its compiler contract pinned; the contract is a byte-identical copy of the v4.211.1 release asset. No new render/runtime probe. Prior: Standalone 4.205.0 and byte-identical compiler contract pinned. Cratis/AI#746: Uuid ==/!= in command require and produces when (ESM v28): same-concept rule, bare Uuid against a concept, canonical literals, protected read paths in require only; PLAY0268 (different concepts, ordering, Uuid validation and concept rules, read paths in produces when) and PLAY0273 (non-canonical literal) checked against the 4.205.0 compiler, v28 selection read from the MCP executable-model view; Stage admits exact v1-v21 and v23-v26 pairs so v28 is refused STAGE-ESM-016, not probed against a Stage image; CLI 3.74.0 renders through v26. Prior: Standalone 4.204.0 and byte-identical compiler contract pinned. Cratis/AI#702 and #691: PLAY0690 reducer identity (Screenplay 4.170.0, native compiler only) and the screenplay.json validation gate (Screenplay 4.165.0; cratis screenplay validate reads it from CLI 3.65.0) are taught and probed against the 4.204.0 compiler. Cratis/AI#743: flat composite read-model keys (ESM v27): untyped projection key blocks on root from and remove with, equality-filter lists, single-instance by blocks and per-part fixtures, with PLAY0661/PLAY0662/PLAY0268 refusals checked against the 4.204.0 compiler; Stage origin/main still refuses v27 with STAGE-ESM-016 (stage-rendering.md); Stage v4.135.0 v26 admission (Host and executor run date comparisons; renderer STAGE-ESM-046) was source-checked for this sync; no render or runtime probe. Prior: Standalone 4.201.0 and byte-identical compiler contract pinned. Cratis/AI#733: the ui profile root template, shell options, appearance and new screens default (PLAY0788-PLAY0799, quick fix for the legacy layout line, ui-profiles MCP tool, 44 tools). Cratis/AI#735: chronological Date/DateTime ordering in command conditions and command/property literal validation (ESM v26), UTC tick precision and pre-rule offset validation; then matching remains ordinal. Source-checked Screenplay v4.199.0 commands, diagnostics, interoperability and specifications documentation plus decision 0087. Stage v4.127.1 still refuses v26 with STAGE-ESM-016 (stage-rendering.md and SemanticVersionFeatures.Supports); no render/runtime probe. Cratis/AI#576: prior mechanical compiler catch-up. Language batch #717/#722/#723/#724/#720/#728/#734 teaches atomic reaction batches (v22), described payload handlers (v23), portable linear matching, ordinal text rules (v24), protected command reads (v25), diagnostic arguments and event-source invokes mappings. Facts read at Screenplay v4.198.0 and introducing tags; Stage v4.127.0 admits exact v1-v21 and v23-v25 pairs but refuses v22/v26 and mixed pairs (STAGE-ESM-016), protected reads (044), atomic mode (043) and described handlers (STAGE-IMPL-002), even Stub mode. Stage text rules execute/render; no new renderer/runtime probe or Stage pin uplift. Cratis/AI#706: application navigation regions (module inherit, extend or override), toolbar slice buttons, blueprint template references and sample data packs in cratis-screenplay-ui-composition (references/application-shell.md), with the canonical shell vector and the rejection codes PLAY0710-PLAY0722 and PLAY0740-PLAY0765. Examples moved to the executable-state rules since 4.164: translator reactions in an Automation slice beside the Translate slice (PLAY0694) and the first record of a capture key appended with `when added`. Earlier: Standalone 4.164.0 and byte-identical compiler contract pinned. Cratis/AI#663: one origin per capture (PLAY0687). #668: executable no-event/redelivery v17. #684: concept query-argument validation in every version and query-error assertions v18. #681: executable refusal branches and refusal values v19. #666: proposal summary/severity counts and exact structural source proposals. Generated-concept rules select v20 with PLAY0688/0689 proofs and derived-matches repair; generated secrets and preview strategies remain refused. Release-baseline from-esm admission reads storedName. Standalone binding is not renderer admission: Stage 4.103.0 admits v1-v17 and v19; CLI 3.62.0 bundles Screenplay 4.159.0 / Stage 4.99.0 and renders through v16. Prior evidence remains unless superseded; no new renderer, Docker or browser probe."
205
205
  },
206
206
  {
207
207
  "id": "scene",
@@ -11,24 +11,23 @@ Read [preferred syntax](../cratis-screenplay-toolchain/references/preferred-synt
11
11
  Prefer the Screenplay MCP tools to text/regex edits: the compiler owns declaration,
12
12
  reference, hierarchy and source evidence for the declarative document set.
13
13
 
14
- Screenplay remains experimental. **Valid source is not necessarily executable.**
15
- It does not generate or run an application; Stage owns rendering/runtime admission.
16
- When selecting construct syntax or distinguishing source validity from execution, read the [language reference](references/language-reference.md) for constructs,
17
- the executable profile and a complete compiled model.
14
+ **Valid source is not necessarily executable.** Stage owns rendering/runtime
15
+ admission. Read the [language reference](references/language-reference.md) for
16
+ construct syntax, source-versus-execution states and a complete compiled model.
18
17
 
19
- For screens: discover UI schemas, propose/apply with revisions, then pass the
20
- same model root or workspace export to all checks. Workflow:
21
- `references/screen-authoring-workflow.md`; syntax/support:
22
- `cratis-screenplay-ui-composition`.
18
+ For screens, read `references/screen-authoring-workflow.md`; use the
19
+ same model root or workspace export for all checks. Syntax: `cratis-screenplay-ui-composition`.
23
20
 
24
21
  Record open modeling questions as `question` notes in committed
25
22
  `.screenplay/notes.json`, not chat or `description` text. Never put secrets or
26
23
  personal data in notes. Read [model notes](references/model-notes.md) when
27
24
  listing, recording or resolving questions: `list-model-notes`,
28
25
  `propose-model-notes`, `read-proposal view=notes`, refs and orphan review.
29
- Prefer dotted split-model targets; inspect `substitutions`, also for reanchor,
30
- and disclose broader owners. The reference covers typed `parts` targets from
31
- `open-workspace.applicationIdentity`.
26
+ Application, Module, Feature and Slice notes anchor before binding; members
27
+ still need binding and otherwise substitute their own slice. Inspect
28
+ `containerIdentities` in `open-workspace` / `workspace-state` for missing or
29
+ ambiguous identities; fix parse/placement errors first. Read the notes reference
30
+ for refusals, `ambiguous: true`, typed targets and every `substitutions` entry.
32
31
 
33
32
  ## Choosing a strategy
34
33
 
@@ -61,8 +60,8 @@ explanatory Markdown belongs in repository documentation.
61
60
  is owned by the Cratis CLI, which preserves other servers and user configuration.
62
61
 
63
62
  The CLI-bundled MCP can be older than the standalone tool: discover schemas.
64
- Read [MCP loop](references/mcp-loop.md) for launch options. Use the supported
65
- channel, not another global tool, Docker or copied managed configuration.
63
+ Read [MCP loop](references/mcp-loop.md) for supported launch channels; do not
64
+ substitute a global tool, Docker or copied managed configuration.
66
65
 
67
66
  If MCP is unavailable, report it; regex edits are not compiler-validated AST
68
67
  editing. Existing standalone `screenplay mcp` users may retain that entry point.
@@ -93,9 +92,8 @@ editing. Existing standalone `screenplay mcp` users may retain that entry point.
93
92
  outlet declarations that provide context. A component binding with no traced
94
93
  data source is not a shortcut; fix the model source.
95
94
 
96
- Keep reads scoped to the relevant module, feature, slice or document. Do not
97
- request a whole merged AST when a bounded declaration/property query answers the
98
- question. Size-limit refusals require narrower reads, not truncation.
95
+ Scope reads to the relevant container/document, not the whole merged AST.
96
+ Size-limit refusals require narrower reads, not truncation.
99
97
 
100
98
  ## Application modes and described handler intent
101
99
 
@@ -111,11 +109,10 @@ Read [comparison sources](references/mcp-tools.md#semantic-revision-comparison)
111
109
 
112
110
  ## Make one coherent proposal
113
111
 
114
- **One edit strategy.** Discover what the server offers. Prefer typed,
115
- identity-preserving operations (`propose-rename`, `propose-repair`,
116
- `propose-extract-inline-event`, `propose-ast`). A bounded text edit is fine only for
117
- edits that leave catalog addresses unchanged (descriptions, rule and expression bodies, mappings
118
- between existing members), never a way around an MCP refusal. When `.screenplay/identities.json`
112
+ **One edit strategy.** Prefer discovered identity-preserving operations
113
+ (`propose-rename`, `propose-repair`, `propose-extract-inline-event`, `propose-ast`).
114
+ Bounded text edits must leave catalog addresses unchanged (descriptions, rule
115
+ bodies, existing-member mappings), never a way around an MCP refusal. When `.screenplay/identities.json`
119
116
  exists, adding, removing or renaming a declaration, command or read-model property, query,
120
117
  query argument or specification goes through MCP, and an `id` pin is not enough for a rename or move. A request naming
121
118
  a rename, move or removal is the approval: do not ask again at `apply`. Without MCP, text-rename
@@ -131,9 +128,10 @@ Others send an edit request ([MCP loop](references/mcp-loop.md)).
131
128
  identity state. `read-workspace` locates document identities.
132
129
  2. `read-ast` returns original occurrence handles and existing semantic IDs.
133
130
  Query `syntax-schema` for exact node members before constructing typed input.
134
- 3. Prefer `propose-rename` for supported logical renames: it coordinates fragments,
135
- repairs proven references and preserves assigned identities. Never substitute
136
- global string replacement for an explicit refusal.
131
+ 3. Prefer `propose-rename` and `propose-move`: they carry identities and notes
132
+ even on unbound models. Manual `propose-ast` / `propose-source` renames need
133
+ `semanticRenames`; removal needs retirement and reports `orphanedNotes`.
134
+ Never substitute global string replacement for an explicit refusal.
137
135
  4. Prefer `propose-property` for property add/rename/remove, not hand-composed
138
136
  `propose-ast` batches. Inspect the chain and never guess past a refusal:
139
137
  [property links](references/property-links.md). Otherwise use `propose-source`
@@ -152,20 +150,17 @@ Others send an edit request ([MCP loop](references/mcp-loop.md)).
152
150
  identity-state change through `workspace-state`. Review `orphanedNotes` on
153
151
  source proposals; reanchor or resolve affected questions before applying
154
152
  ([notes and orphan impact](references/model-notes.md#source-proposals-can-orphan-notes)).
155
- 7. Run `run-specifications` with `proposalId` before applying. Record V4 separately: PLAY0285
156
- (impossible `then`) unbinds the whole model. Paging and read-only candidate semantics:
157
- [MCP tool guide](references/mcp-tools.md#run-reference-specifications).
158
-
159
- Requires Screenplay 4.145.0 or later (`screenplay --version`) for `proposalId`; earlier servers run only the current workspace.
153
+ 7. Run `run-specifications` with `proposalId` before applying; record V4 separately.
154
+ PLAY0285 unbinds the whole model. Read the [MCP tool guide](references/mcp-tools.md#run-reference-specifications)
155
+ for candidate paging and the required version.
160
156
  8. `apply` only the reviewed server-produced proposal within the user's requested
161
157
  change. The proposal ID and before revisions are required; stale state rejects.
162
- When the user already requested apply, do it after checks without asking again;
163
- otherwise show the proposal and ask once.
158
+ Apply after checks if requested; otherwise show the proposal and ask once.
164
159
  9. When the host draws views, `visualize-model` shows the board. It follows the files
165
160
  on disk while open, so after an apply do not re-request it; just say what changed.
166
161
 
167
- Handles are revision-bound occurrences, not durable IDs. Modules/features can
168
- span fragments; one header edit may not change all. After apply, fetch fresh handles/revisions.
162
+ Handles are revision-bound, not durable IDs. Modules/features span fragments;
163
+ after apply fetch fresh handles/revisions.
169
164
 
170
165
  On refusal, use `failureKind`, never message text ([failures/limits](references/mcp-loop.md#failures-use-failurekind-never-message-text)).
171
166
  After revision/disk/identity drift, reopen and re-propose. For `ApplyOutcomeUnknown`
@@ -188,6 +183,8 @@ Use `recommend-layout` for options and review an `expand-layout` proposal; layou
188
183
 
189
184
  ## Preserve state and recover explicitly
190
185
 
186
+ Fix binding errors through MCP proposals, not outside MCP: reopening after an
187
+ external fix can require reconciliation of a persisted partial catalog.
191
188
  Commit `.screenplay/identities.json` with the model; only `apply` writes it. Never delete or overwrite identity state, mint IDs on restart, or text-rename identity-affecting declarations. A pending journal blocks normal work: inspect `workspace-state` and use `recover-workspace` only for the identified interrupted operation. Only `apply` / `recover-workspace` write source/catalog. `readiness.authoringAccepted` says the source is valid Screenplay; `executableReady` is separate. Read [references/state-and-recovery.md](references/state-and-recovery.md) for root conflicts, journals and readiness.
192
189
 
193
190
  ## Code attachments
@@ -199,8 +196,8 @@ are not behavioral evidence.
199
196
 
200
197
  ## Verify and report honestly
201
198
 
202
- - Require zero source errors and investigate every warning.
203
- - Confirm reference safety, identity continuity and exact intended source changes.
199
+ - Require zero source errors; investigate warnings, reference safety, identity
200
+ continuity and exact intended changes.
204
201
  - Report which of the four states you checked: **parsed**, **bound**,
205
202
  **reference-executed**, **target-executed**. When distinguishing source validity from execution, read the
206
203
  [language reference](references/language-reference.md#source-validity-is-not-execution);
@@ -209,9 +206,8 @@ are not behavioral evidence.
209
206
  clean run is not a bound or executable result.
210
207
  - Never drop or stub source contracts to bind; the bundled compiler and renderer can be older than the standalone tool. Read [references/language-reference.md](references/language-reference.md) for the ESM version at which each construct binds.
211
208
 
212
- - Distinguish authoring acceptance from `executableReady`; unsupported backend
213
- capabilities are not a reason to drop source constructs or invent stubs.
214
- - If execution is intended, validate with the owning downstream runtime as well.
209
+ - Unsupported capabilities never justify dropping constructs or inventing stubs.
210
+ Validate intended execution with the owning downstream runtime.
215
211
  - Model rejection cases as specifications; assertion presence is not execution.
216
212
  - Check installed `tools/list`/schemas rather than assuming a remembered tool count.
217
213
 
@@ -221,9 +217,9 @@ The ordinary CLI remains useful for whole-folder validation:
221
217
  cratis screenplay validate <model-folder> --warnings-as-errors
222
218
  ```
223
219
 
224
- Record screen MCP transcripts in `.ai-work/`; render/runtime checks must use the
225
- same source, never an app that silently drops authored UI. Use the Screenplay-owned canonical
226
- corpus fixture path instead of copying available `.play` fixtures here.
220
+ Keep screen transcripts in `.ai-work/`; check the same source, never an app that
221
+ silently drops authored UI. Use the Screenplay-owned canonical
222
+ corpus fixture path instead of copying fixtures here.
227
223
 
228
224
  Never invent syntax or capabilities.
229
225
 
@@ -235,10 +231,10 @@ Never invent syntax or capabilities.
235
231
  | Commands, events, validation and concurrency | `cratis-screenplay-command-surface` |
236
232
  | Projections and reducers | `cratis-screenplay-projections` |
237
233
  | Read models, queries and screens | `cratis-screenplay-read-surface` |
238
- | Layouts, forms, contributions, navigation regions, slice buttons, template references, sample data, component bindings, toolbars, outlets, themes and localization | `cratis-screenplay-ui-composition` |
234
+ | UI composition, bindings, navigation and themes | `cratis-screenplay-ui-composition` |
239
235
  | Captures, reactions and triggers | `cratis-screenplay-captures-and-reactions` |
240
236
  | Behavioral examples and assertions | `cratis-screenplay-specifications` |
241
237
  | Rendering/running an admitted model | `cratis-stage-rendering-and-sandbox` |
242
- | Lifecycle, verdicts V1 to V5 and the model-first decision | `cratis-screenplay-modeling-lifecycle` |
243
- | Compiler, CLI and MCP versions, diagnostics, capability tables | `cratis-screenplay-toolchain` |
238
+ | Lifecycle and model-first decision | `cratis-screenplay-modeling-lifecycle` |
239
+ | Compiler, CLI, MCP and diagnostics | `cratis-screenplay-toolchain` |
244
240
  | Event-model diagrams rather than .play source | `cratis-event-model-diagram` |
@@ -281,9 +281,14 @@ Requires Screenplay 4.89.0 or later (`screenplay --version`) for `identityMigrat
281
281
 
282
282
  ## Identity state (`.screenplay/identities.json`)
283
283
 
284
- - `apply` persists identities with the `.play` changes (probed: the file survives
285
- restarts without `export-workspace`). `open-workspace` and read-only commands
286
- never create it. Commit both.
284
+ - `apply` persists identities with source or notes-only changes; they survive
285
+ restarts without `export-workspace`. `open-workspace` and read-only commands
286
+ never create the file. Commit identity state with the model and notes.
287
+ - Containers anchor before binding when all documents parse and place; inspect
288
+ `containerIdentities` in `open-workspace` / `workspace-state`. Fix binding
289
+ through MCP proposals, not external edits after persisting a partial catalog.
290
+ Read [state and recovery](state-and-recovery.md) for the exact unbound reopen
291
+ exception and [model notes](model-notes.md) for targeting refusal reasons.
287
292
  - A model only ever edited as text has **no persisted identities** until the first
288
293
  `apply`. Whether a first apply is the intended initialization is not documented
289
294
  beyond "after the first apply, keep `.screenplay/identities.json`"; ask before
@@ -127,6 +127,32 @@ A folder is one application; a file selects only itself and its imports.
127
127
 
128
128
  ## Whole-source authoring
129
129
 
130
+ Application notes already anchor before binding; Module, Feature and Slice
131
+ identities materialize from the authoring hierarchy when every document parses
132
+ and places. Binding keeps those IDs. Read `containerIdentities` in
133
+ `open-workspace` / `workspace-state`: `complete`, `containers` (`address`,
134
+ `reason`, `assigned`) and `documents` (`path`, `reason`). Reasons are `ambiguous`,
135
+ `idCollision`, `incomplete`, `unparsed` and `unplaced`; incomplete documents stop
136
+ all new assignments, not just their own. Fix parse/placement errors first.
137
+ Notes tools refuse unavailable targets and descendants with the same reasons in
138
+ all forms. Existing notes on ambiguous containers remain resolved with
139
+ `ambiguous: true`; inspect them unfiltered or by existing `semanticId`.
140
+ Unidentified members still need binding and substitute their own slice in
141
+ `substitutions`, never silently promote to a feature/module. Details:
142
+ [model notes](model-notes.md#anchors-and-independent-state).
143
+
144
+ Requires Screenplay 4.213.0 (`screenplay --version`) for pre-binding container
145
+ identities and reporting; upgrade older servers before relying on direct
146
+ container anchoring.
147
+
148
+ `propose-rename` and `propose-move` preserve assigned container identities and
149
+ notes on unbound models, including before first binding. Manual `propose-ast` /
150
+ `propose-source` renames need `semanticRenames`, removals need
151
+ `retiredSemanticAddresses` and report `orphanedNotes`. Fix binding errors through
152
+ MCP proposals so reopening does not require reconciliation after an external fix.
153
+ Opening computes identities in memory only; even notes-only `apply` can persist
154
+ them with notes under the same rollback journal.
155
+
130
156
  `propose-source` takes `expectedRevision`, `expectedCatalogRevision`, explicit
131
157
  `formatting` and `documents`. Default `validation: "Authoring"` accepts syntax-only
132
158
  models; `"Executable"` requires binding and never falls back. Default
@@ -63,11 +63,38 @@ a Module (replace the Application key with that response's value):
63
63
  }
64
64
  ```
65
65
 
66
- A typed address needs an existing catalog identity; it refuses when none exists.
67
- Use the construct's current source handle instead. A target without an identity
68
- lands on the nearest identified slice, feature, module or application. On an
69
- unbound model, even a Slice can lack an identity and fall back to Application;
70
- opening the workspace does not guarantee container identities.
66
+ Application notes anchor as `{ application: true }` before binding. Modules,
67
+ nested Features and Slices gain deterministic catalog identities from the
68
+ authoring hierarchy before the model binds, provided every document parses and
69
+ places. Dotted, typed and source-handle targets anchor directly to those
70
+ containers without substitution. Binding preserves their existing IDs and
71
+ origins; never calculate an ID client-side.
72
+
73
+ Commands, events, read models, projections, queries, specifications, reactions,
74
+ captures and properties still need a bound model for their own identities. Until
75
+ then, their notes land on their own slice, not the feature or module, and are
76
+ reported in `substitutions`. Name the intended member in the text.
77
+
78
+ Requires Screenplay 4.213.0 (`screenplay --version`) for pre-binding container
79
+ identities and identity-problem reporting. Older servers can broaden container
80
+ notes to an identified ancestor; upgrade before relying on direct anchoring.
81
+
82
+ Inspect `containerIdentities` from `open-workspace` and `workspace-state` when
83
+ identities are missing. It contains `complete`, `containers` entries with
84
+ `address`, `reason`, `assigned`, and `documents` entries with `path`, `reason`.
85
+ Container reasons are `ambiguous`, `idCollision` or `incomplete`; document reasons
86
+ are `unparsed` or `unplaced`. Fix parse and import-placement errors first:
87
+ **no new identities are assigned anywhere** until every document parses and
88
+ places, even in otherwise valid documents. Existing assignments are retained.
89
+ Unavailable containers and descendants refuse new note targeting with the same
90
+ reason in every form, including semantic-ID anchors; do not bypass a refusal by
91
+ requesting a broader owner. Repeated Module/Feature fragments count as one logical
92
+ declaration; duplicate Slices do not.
93
+
94
+ A container duplicated outside MCP keeps its identity and notes. Existing notes
95
+ on it or its descendants stay resolved with `ambiguous: true`, not orphaned.
96
+ Read them unfiltered or by their existing `semanticId`; new targeting on the
97
+ ambiguous container or its descendants is refused.
71
98
 
72
99
  Always inspect `substitutions` for both `add` and `reanchor`, even when reanchor
73
100
  leaves the note unchanged. Each entry has the requested `target`, resolved
@@ -82,8 +109,12 @@ reporting. Older servers can refuse split targets, omit that field or silently
82
109
  broaden the anchor; use a catalog address/current handle and inspect the notes
83
110
  review's actual anchor, or upgrade before relying on these responses.
84
111
 
85
- Notes do not change source, workspace/catalog/semantic revisions, executable
86
- model bytes or compiler verdicts. Their own `notesRevision` is `nrev1:` plus the
112
+ Notes do not change source, executable model bytes or compiler verdicts.
113
+ Opening or proposing an unbound workspace can materialize container assignments
114
+ in memory and advance its catalog revision. Opening never writes them; a
115
+ notes-only `apply` can persist them in `.screenplay/identities.json` under the
116
+ same journal as the sidecar. Rollback restores both the notes and exact earlier
117
+ identity state. Notes retain an independent revision; their `notesRevision` is `nrev1:` plus the
87
118
  lowercase SHA-256 of canonical bytes; `nrev1:absent` is not an empty document.
88
119
  The file header uses `schema: "cratis.screenplay.notes"`, `schemaVersion: 1` and
89
120
  `applicationIdentity` in the catalog's representation. The server writes stable
@@ -205,12 +236,27 @@ stops being adequate.
205
236
 
206
237
  ## Source proposals can orphan notes
207
238
 
239
+ Prefer `propose-rename` and `propose-move`: identities and notes follow containers
240
+ on unbound models as on bound ones, including before their first binding. A
241
+ manual `propose-ast` or `propose-source` rename needs explicit `semanticRenames`;
242
+ removal needs `retiredSemanticAddresses`. Retirement is not a substitute for a
243
+ rename when continuity is intended.
244
+
245
+ Fix binding errors through MCP proposals. After a partial catalog is persisted,
246
+ fixing binding outside MCP can add bound identities on reopen and require
247
+ reconciliation; never discard state to bypass it.
248
+
208
249
  Review `orphanedNotes` IDs and `notes` status/reason/count on source, AST, rename,
209
250
  move and property proposals and their reviews. Retirement leaves a computed
210
251
  orphan with null current address and `orphanReason: "unknown"`; notes are never
211
252
  silently deleted. `orphanedNotes: null` with unreadable notes means unknown
212
253
  impact, not `[]`.
213
254
 
255
+ Re-adding a retired address recreates its deterministic identity only when source
256
+ is complete and unambiguous. Orphaned notes resolve again only for their exact
257
+ former ID. An identity previously carried there by rename or assigned externally
258
+ may differ; explicitly reanchor those notes.
259
+
214
260
  Before applying a source proposal, review each affected question: reanchor to a
215
261
  surviving element, or resolve with evidence and deliberately decide whether to
216
262
  retain its orphaned history. Resolution alone does not restore an anchor. Remove
@@ -10,6 +10,28 @@ Commit `.screenplay/identities.json` with the model. Only `apply` writes it;
10
10
  overwrite conflicting identity state, silently mint IDs on restart, or text-rename
11
11
  identity-affecting declarations in a model that has it.
12
12
 
13
+ An unbound workspace materializes collision-free deterministic Module, Feature
14
+ and Slice identities in memory when every document parses and places. Application
15
+ notes already anchor before binding. Opening never writes state; `apply`,
16
+ including a notes-only apply, persists these assignments. Binding preserves their
17
+ IDs and origins, and rename/move proposals carry identities and notes before
18
+ first binding. Read `containerIdentities` from `open-workspace` / `workspace-state`
19
+ and the [notes guidance](model-notes.md#anchors-and-independent-state) for
20
+ ambiguity, collision and incomplete-source refusals.
21
+
22
+ Reopening persisted unbound state admits only deterministic container additions:
23
+ every document must parse and place; every previous assignment must still be
24
+ present in source; earlier IDs, origins, event revisions, document mappings and
25
+ application metadata must be unchanged. Other drift still requires reconciliation.
26
+ A supplied `workspaceJson` cannot replace different persisted identity authority.
27
+ Fix binding errors through MCP proposals: an external fix after a partial catalog
28
+ was persisted can add bound identities on reopen and require reconciliation.
29
+ Never delete state to bypass that refusal.
30
+
31
+ A notes apply journals the sidecar and any new container identities together;
32
+ rollback restores exact earlier identity bytes as well as notes, including an
33
+ earlier catalog without those containers.
34
+
13
35
  Default root discovery preserves ancestor identity state and journals. Inspect
14
36
  `rootBindingConflict` in `open-workspace`/`workspace-state` when several state roots
15
37
  compete; do not delete state or mint replacement identities. To recover a competing
@@ -40,7 +40,23 @@
40
40
  { "kind": "skill-contains", "value": "`applicationIdentity` returned by `open-workspace`", "file": "references/model-notes.md" },
41
41
  { "kind": "skill-contains", "value": "Repeated Module/Feature headers", "file": "references/model-notes.md" },
42
42
  { "kind": "skill-contains", "value": "Always inspect `substitutions` for both `add` and `reanchor`", "file": "references/model-notes.md" },
43
- { "kind": "skill-contains", "value": "even a Slice can lack an identity", "file": "references/model-notes.md" },
43
+ { "kind": "skill-contains", "value": "before the model binds", "file": "references/model-notes.md" },
44
+ { "kind": "skill-contains", "value": "Application, Module, Feature and Slice notes anchor before binding" },
45
+ { "kind": "skill-contains", "value": "Binding preserves their existing IDs and", "file": "references/model-notes.md" },
46
+ { "kind": "skill-contains", "value": "their notes land on their own slice, not the feature or module", "file": "references/model-notes.md" },
47
+ { "kind": "skill-contains", "value": "`containerIdentities`", "file": "references/mcp-tools.md" },
48
+ { "kind": "skill-contains", "value": "`ambiguous`, `idCollision` or `incomplete`", "file": "references/model-notes.md" },
49
+ { "kind": "skill-contains", "value": "`unparsed` or `unplaced`", "file": "references/model-notes.md" },
50
+ { "kind": "skill-contains", "value": "**no new identities are assigned anywhere**", "file": "references/model-notes.md" },
51
+ { "kind": "skill-contains", "value": "reason in every form, including semantic-ID anchors", "file": "references/model-notes.md" },
52
+ { "kind": "skill-contains", "value": "stay resolved with `ambiguous: true`, not orphaned", "file": "references/model-notes.md" },
53
+ { "kind": "skill-contains", "value": "notes on unbound models, including before first binding", "file": "references/mcp-tools.md" },
54
+ { "kind": "skill-contains", "value": "`semanticRenames`", "file": "references/model-notes.md" },
55
+ { "kind": "skill-contains", "value": "`retiredSemanticAddresses`", "file": "references/model-notes.md" },
56
+ { "kind": "skill-contains", "value": "Fix binding errors through MCP proposals", "file": "references/model-notes.md" },
57
+ { "kind": "skill-contains", "value": "rollback restores exact earlier identity bytes as well as notes", "file": "references/state-and-recovery.md" },
58
+ { "kind": "skill-contains", "value": "Orphaned notes resolve again only for their exact", "file": "references/model-notes.md" },
59
+ { "kind": "skill-contains", "value": "Requires Screenplay 4.213.0", "file": "references/model-notes.md" },
44
60
  { "kind": "skill-contains", "value": "older servers miss the read-only denial for SPEC004 and count it for SPEC006", "file": "references/mcp-tools.md" },
45
61
  { "kind": "skill-contains", "value": "`anchor`", "file": "references/model-notes.md" },
46
62
  { "kind": "skill-contains", "value": "`scope`", "file": "references/model-notes.md" },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cratis/pi",
3
- "version": "7.79.0",
3
+ "version": "7.80.0",
4
4
  "description": "Configuration-aware Cratis AI integration for Pi",
5
5
  "type": "module",
6
6
  "files": [