@dxos/deus 0.0.0-stage → 0.0.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.
Files changed (201) hide show
  1. package/LICENSE +105 -0
  2. package/README.md +24 -2
  3. package/bin/deus.ts +42 -0
  4. package/dist/lib/chunk-blocks.mjs +151 -0
  5. package/dist/lib/chunk-blocks.mjs.map +1 -0
  6. package/dist/lib/chunk-check.mjs +452 -0
  7. package/dist/lib/chunk-check.mjs.map +1 -0
  8. package/dist/lib/chunk-completion.mjs +112 -0
  9. package/dist/lib/chunk-completion.mjs.map +1 -0
  10. package/dist/lib/chunk-extension.mjs +396 -0
  11. package/dist/lib/chunk-extension.mjs.map +1 -0
  12. package/dist/lib/chunk-parse.mjs +21 -0
  13. package/dist/lib/chunk-parse.mjs.map +1 -0
  14. package/dist/lib/cli.mjs +946 -0
  15. package/dist/lib/cli.mjs.map +1 -0
  16. package/dist/lib/extension.mjs +4 -0
  17. package/dist/lib/index.mjs +6 -0
  18. package/dist/lib/parse.mjs +4 -0
  19. package/dist/lib/review.mjs +260 -0
  20. package/dist/lib/review.mjs.map +1 -0
  21. package/dist/lib/spec-index.mjs +28 -0
  22. package/dist/lib/spec-index.mjs.map +1 -0
  23. package/dist/types/bin/deus.d.ts +3 -0
  24. package/dist/types/bin/deus.d.ts.map +1 -0
  25. package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
  26. package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
  27. package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
  28. package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
  29. package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
  30. package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
  31. package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
  32. package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
  33. package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
  34. package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
  35. package/dist/types/src/cli/changelog.d.ts +25 -0
  36. package/dist/types/src/cli/changelog.d.ts.map +1 -0
  37. package/dist/types/src/cli/cli.test.d.ts +2 -0
  38. package/dist/types/src/cli/cli.test.d.ts.map +1 -0
  39. package/dist/types/src/cli/errors.d.ts +183 -0
  40. package/dist/types/src/cli/errors.d.ts.map +1 -0
  41. package/dist/types/src/cli/features.d.ts +58 -0
  42. package/dist/types/src/cli/features.d.ts.map +1 -0
  43. package/dist/types/src/cli/git.d.ts +8 -0
  44. package/dist/types/src/cli/git.d.ts.map +1 -0
  45. package/dist/types/src/cli/index.d.ts +12 -0
  46. package/dist/types/src/cli/index.d.ts.map +1 -0
  47. package/dist/types/src/cli/lint.d.ts +17 -0
  48. package/dist/types/src/cli/lint.d.ts.map +1 -0
  49. package/dist/types/src/cli/qa-lint.d.ts +40 -0
  50. package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
  51. package/dist/types/src/cli/qa.d.ts +86 -0
  52. package/dist/types/src/cli/qa.d.ts.map +1 -0
  53. package/dist/types/src/cli/review.d.ts +38 -0
  54. package/dist/types/src/cli/review.d.ts.map +1 -0
  55. package/dist/types/src/cli/spec-index.d.ts +17 -0
  56. package/dist/types/src/cli/spec-index.d.ts.map +1 -0
  57. package/dist/types/src/extension/blocks.d.ts +65 -0
  58. package/dist/types/src/extension/blocks.d.ts.map +1 -0
  59. package/dist/types/src/extension/check.d.ts +99 -0
  60. package/dist/types/src/extension/check.d.ts.map +1 -0
  61. package/dist/types/src/extension/check.test.d.ts +2 -0
  62. package/dist/types/src/extension/check.test.d.ts.map +1 -0
  63. package/dist/types/src/extension/code.d.ts +7 -0
  64. package/dist/types/src/extension/code.d.ts.map +1 -0
  65. package/dist/types/src/extension/complete.d.ts +6 -0
  66. package/dist/types/src/extension/complete.d.ts.map +1 -0
  67. package/dist/types/src/extension/completion.d.ts +10 -0
  68. package/dist/types/src/extension/completion.d.ts.map +1 -0
  69. package/dist/types/src/extension/constants.d.ts +6 -0
  70. package/dist/types/src/extension/constants.d.ts.map +1 -0
  71. package/dist/types/src/extension/fences.d.ts +10 -0
  72. package/dist/types/src/extension/fences.d.ts.map +1 -0
  73. package/dist/types/src/extension/gen/mdl.d.ts +3 -0
  74. package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
  75. package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
  76. package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
  77. package/dist/types/src/extension/index.d.ts +8 -0
  78. package/dist/types/src/extension/index.d.ts.map +1 -0
  79. package/dist/types/src/extension/language.d.ts +20 -0
  80. package/dist/types/src/extension/language.d.ts.map +1 -0
  81. package/dist/types/src/extension/lint.d.ts +8 -0
  82. package/dist/types/src/extension/lint.d.ts.map +1 -0
  83. package/dist/types/src/extension/parse.d.ts +6 -0
  84. package/dist/types/src/extension/parse.d.ts.map +1 -0
  85. package/dist/types/src/extension/parser.test.d.ts +2 -0
  86. package/dist/types/src/extension/parser.test.d.ts.map +1 -0
  87. package/dist/types/src/extension/refs.d.ts +32 -0
  88. package/dist/types/src/extension/refs.d.ts.map +1 -0
  89. package/dist/types/src/extension/refs.test.d.ts +2 -0
  90. package/dist/types/src/extension/refs.test.d.ts.map +1 -0
  91. package/dist/types/src/extension/syntax.d.ts +12 -0
  92. package/dist/types/src/extension/syntax.d.ts.map +1 -0
  93. package/dist/types/src/index.d.ts +3 -0
  94. package/dist/types/src/index.d.ts.map +1 -0
  95. package/dist/types/src/review/fields.d.ts +9 -0
  96. package/dist/types/src/review/fields.d.ts.map +1 -0
  97. package/dist/types/src/review/index.d.ts +5 -0
  98. package/dist/types/src/review/index.d.ts.map +1 -0
  99. package/dist/types/src/review/review.d.ts +70 -0
  100. package/dist/types/src/review/review.d.ts.map +1 -0
  101. package/dist/types/src/review/review.test.d.ts +2 -0
  102. package/dist/types/src/review/review.test.d.ts.map +1 -0
  103. package/dist/types/src/review/source-key.d.ts +35 -0
  104. package/dist/types/src/review/source-key.d.ts.map +1 -0
  105. package/dist/types/src/review/symbol.d.ts +17 -0
  106. package/dist/types/src/review/symbol.d.ts.map +1 -0
  107. package/dist/types/src/review/symbol.test.d.ts +2 -0
  108. package/dist/types/src/review/symbol.test.d.ts.map +1 -0
  109. package/dist/types/src/spec-index/index.d.ts +3 -0
  110. package/dist/types/src/spec-index/index.d.ts.map +1 -0
  111. package/dist/types/src/spec-index/parse.d.ts +11 -0
  112. package/dist/types/src/spec-index/parse.d.ts.map +1 -0
  113. package/dist/types/src/spec-index/spec-index.d.ts +21 -0
  114. package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
  115. package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
  116. package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
  117. package/dist/types/tsconfig.tsbuildinfo +1 -0
  118. package/docs/DESIGN.md +561 -0
  119. package/docs/IDIOMS.md +265 -0
  120. package/lang/PLUGIN-.template.mdl +115 -0
  121. package/lang/app.mdl +200 -0
  122. package/lang/changelog.mdl +184 -0
  123. package/lang/core.mdl +203 -0
  124. package/lang/examples/chess-1.mdl +149 -0
  125. package/lang/examples/chess-2.mdl +203 -0
  126. package/lang/examples/chess-3.mdl +231 -0
  127. package/lang/features.mdl +92 -0
  128. package/lang/plugin.mdl +59 -0
  129. package/lang/qa.mdl +383 -0
  130. package/lang/review.mdl +103 -0
  131. package/lang/sql.mdl +72 -0
  132. package/package.json +74 -3
  133. package/src/cli/__fixtures__/bad-decision.mdl +13 -0
  134. package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
  135. package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
  136. package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
  137. package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
  138. package/src/cli/__fixtures__/features/TASKS.md +5 -0
  139. package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
  140. package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
  141. package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
  142. package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
  143. package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
  144. package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
  145. package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
  146. package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
  147. package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
  148. package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
  149. package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
  150. package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
  151. package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
  152. package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
  153. package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
  154. package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
  155. package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
  156. package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
  157. package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
  158. package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
  159. package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
  160. package/src/cli/changelog.ts +122 -0
  161. package/src/cli/cli.test.ts +359 -0
  162. package/src/cli/errors.ts +23 -0
  163. package/src/cli/features.ts +320 -0
  164. package/src/cli/git.ts +35 -0
  165. package/src/cli/index.ts +27 -0
  166. package/src/cli/lint.ts +75 -0
  167. package/src/cli/qa-lint.ts +206 -0
  168. package/src/cli/qa.ts +300 -0
  169. package/src/cli/review.ts +359 -0
  170. package/src/cli/spec-index.ts +54 -0
  171. package/src/extension/blocks.ts +169 -0
  172. package/src/extension/check.test.ts +629 -0
  173. package/src/extension/check.ts +552 -0
  174. package/src/extension/code.ts +99 -0
  175. package/src/extension/complete.ts +34 -0
  176. package/src/extension/completion.ts +64 -0
  177. package/src/extension/constants.ts +28 -0
  178. package/src/extension/fences.ts +270 -0
  179. package/src/extension/gen/mdl.terms.ts +16 -0
  180. package/src/extension/gen/mdl.ts +16 -0
  181. package/src/extension/index.ts +25 -0
  182. package/src/extension/language.ts +33 -0
  183. package/src/extension/lint.ts +19 -0
  184. package/src/extension/mdl.grammar +60 -0
  185. package/src/extension/parse.ts +31 -0
  186. package/src/extension/parser.test.ts +248 -0
  187. package/src/extension/refs.test.ts +95 -0
  188. package/src/extension/refs.ts +94 -0
  189. package/src/extension/syntax.ts +25 -0
  190. package/src/index.ts +6 -0
  191. package/src/review/fields.ts +31 -0
  192. package/src/review/index.ts +8 -0
  193. package/src/review/review.test.ts +111 -0
  194. package/src/review/review.ts +184 -0
  195. package/src/review/source-key.ts +63 -0
  196. package/src/review/symbol.test.ts +47 -0
  197. package/src/review/symbol.ts +96 -0
  198. package/src/spec-index/index.ts +6 -0
  199. package/src/spec-index/parse.ts +22 -0
  200. package/src/spec-index/spec-index.test.ts +56 -0
  201. package/src/spec-index/spec-index.ts +49 -0
package/docs/DESIGN.md ADDED
@@ -0,0 +1,561 @@
1
+ # DEUS EX MACHINA
2
+
3
+ ```
4
+ ________ _______________ ___ _________
5
+ \______ \ \_ _____/ | \/ _____/
6
+ | | \ | __)_| | /\_____ \
7
+ | ` \| \ | / / \
8
+ /_______ /_______ /______/ /_______ /
9
+ \/ \/ \/
10
+ ```
11
+
12
+ > A pattern specification language for human-agent collaborative software development.
13
+
14
+ > "To work our way towards a shared language once again, we must first learn how to discover patterns which are deep, and capable of generating life."
15
+ > — Christopher Alexander, The Timeless Way of Building
16
+
17
+ > "No pattern is an isolated entity. Each pattern can exist in the world, only to the extent that is supported by other patterns: the larger patterns in which it is embedded, the patterns of the same size that surround it, and the smaller patterns which are embedded in it."
18
+ > — Christopher Alexander, A Pattern Language
19
+
20
+ > "Each pattern describes a problem which occurs over and over again in our environment, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice."
21
+ > — Christopher Alexander, A Pattern Language
22
+
23
+ ## Overview
24
+
25
+ Deus is a semi-formal, human-readable specification language for software systems.
26
+ A `.mdl` file is the authoritative description of a system — its types, behaviour,
27
+ interfaces, and acceptance criteria — from which implementation, tests, and documentation
28
+ can all be derived.
29
+
30
+ The language is built around a single primitive (`ext`) and a universal extension
31
+ mechanism. The standard vocabulary (`type`, `op`, `component`, `service`, `feat`, `scenario`)
32
+ is itself defined using that mechanism, and any project can introduce new constructs
33
+ the same way.
34
+
35
+ Deus is designed for a world where humans and agents collaborate: the human describes
36
+ intent in natural language, Deus captures it precisely enough for an agent to design,
37
+ implement, and verify — then proposes amendments when reality drifts from the spec.
38
+
39
+ ## Motivation
40
+
41
+ Software specifications exist on a spectrum. At one end: dense prose documents that
42
+ humans can read but agents cannot act on. At the other: formal languages that machines
43
+ can verify but no one wants to write. In practice most teams have neither — intent
44
+ lives in tickets, Slack threads, and the author's head.
45
+
46
+ Deus occupies the middle ground: compact, structured, and readable without being
47
+ a proof system. It is precise enough to drive agents, loose enough to evolve with
48
+ the project, and human enough to serve as the shared language a team actually uses.
49
+
50
+ The name resonates with its purpose: _deus ex machina_ — the authoritative source
51
+ from which the machine derives everything else.
52
+
53
+ ## Design Principles
54
+
55
+ **Prose-first, structure on demand.**
56
+ Simple requirements stay as prose. Complex ones get `when/then`. The language
57
+ never forces ceremony on things that don't need it.
58
+
59
+ **One primitive, infinite vocabulary.**
60
+ The only built-in construct is `ext`. Everything else — types, operations,
61
+ components, features, tests — is declared using `ext`. Users and agents extend
62
+ the language the same way the standard dialect is built.
63
+
64
+ **Layers, not monoliths.**
65
+ Specs compose via `extends`. A DXOS plugin spec extends `Deus.DXOS`, which
66
+ extends `Deus.Std`, which extends `Deus.Core`. Each layer adds vocabulary;
67
+ no layer breaks the ones above it.
68
+
69
+ **Structural and behavioural concerns are separate.**
70
+ Structural blocks (`type`, `op`, `component`, `service`) describe _what exists_.
71
+ Behavioural blocks (`feat`, `req`) describe _how things behave_. Tests validate both.
72
+ Features are the glue — they cross-reference structural elements explicitly.
73
+
74
+ **Pure before effectful.**
75
+ Operations declare whether they are pure (no `effects`, no `requires`) or effectful.
76
+ This distinction surfaces in the spec, not just in the code.
77
+
78
+ **The spec is the source of truth.**
79
+ Round-trip tooling keeps implementation and spec in sync. Agents read the spec
80
+ to implement; they read the code to propose spec amendments.
81
+
82
+ ## Core Language
83
+
84
+ ### Document Format
85
+
86
+ A `.mdl` file has three parts:
87
+
88
+ 1. **Frontmatter** — YAML delimited by `---`. Contains document metadata.
89
+ 2. **Body** — Standard Markdown prose, headings, and lists.
90
+ 3. **Blocks** — Typed fenced sections carrying structured declarations.
91
+
92
+ ```
93
+ ---
94
+ id: URI # globally unique document identifier
95
+ name: Identifier # human-readable name
96
+ version: SemVer
97
+ extends?: URI[] # specs this document extends (transitive)
98
+ ---
99
+ ```
100
+
101
+ All blocks use the `mdl` fence. The first body line declares the block type,
102
+ optional identifier, and optional title:
103
+
104
+ ````
105
+ ```mdl
106
+ type [id][: title]
107
+ key: value
108
+ key?: TypeExpr
109
+ key: a | b | c
110
+ ```
111
+ ````
112
+
113
+ ### The `ext` Primitive
114
+
115
+ `ext` is the only block type the core language provides. It is self-describing:
116
+
117
+ ```mdl
118
+ ext ext
119
+ uri: org.dxos/core/ext
120
+ desc: Declares a new block type or extends an existing one.
121
+ fields:
122
+ uri: URI
123
+ desc: Prose
124
+ extends?: ExtRef
125
+ fields?: FieldMap
126
+ adds-fields?: FieldMap
127
+ nesting?: self | none
128
+ inline-prose?: Boolean
129
+ example?: CodeBlock
130
+ ```
131
+
132
+ ### Primitive Types
133
+
134
+ The meta-vocabulary used within `ext` field declarations:
135
+
136
+ | Type | Description |
137
+ | ------------ | ------------------------------------------------------ |
138
+ | `Prose` | Free-form text, single or multi-line |
139
+ | `Identifier` | Alphanumeric name, hyphens allowed |
140
+ | `URI` | Dot-path or URL identifier |
141
+ | `SemVer` | Semantic version string |
142
+ | `Boolean` | `true` or `false` |
143
+ | `TypeExpr` | Type reference or inline type — e.g. `Color`, `Piece?` |
144
+ | `FieldMap` | Named fields: `name[?]: TypeExpr # comment` |
145
+ | `UnionList` | Pipe-separated literals: `a \| b \| c` |
146
+ | `ProseList` | Bulleted list of prose items |
147
+ | `CodeBlock` | Literal indented or fenced text |
148
+ | `ExtRef` | Reference to a declared extension name |
149
+ | `TagList` | Space or comma-separated tag identifiers |
150
+
151
+ ### Cross-References
152
+
153
+ Any declared block identifier may be referenced elsewhere as `[id]`.
154
+ Blocks in other layers may be referenced with a type prefix: `op:submitMove`,
155
+ `component:Gameboard`. The linter verifies all references resolve.
156
+
157
+ ### Resolution Rules
158
+
159
+ 1. A block type must appear in the document's Extensions table or an ancestor's.
160
+ 2. If the URI matches an inline `ext` in an Appendix, that definition is used.
161
+ 3. Otherwise the URI is resolved from an external registry.
162
+ 4. Unresolvable block types are lint errors. Unknown fields are lint warnings.
163
+
164
+ ## Extension Mechanism
165
+
166
+ ### Declaring Extensions
167
+
168
+ Every document lists its vocabulary upfront in an Extensions table:
169
+
170
+ ```
171
+ ## Extensions
172
+
173
+ | Term | URI |
174
+ | ----------- | -------------------------- |
175
+ | `type` | org.dxos.mdl.type@1.0 |
176
+ | `component` | org.dxos.mdl.component@1.0 |
177
+ ```
178
+
179
+ This is the manifest — agents know which dialects apply before reading the body.
180
+
181
+ ### Defining Extensions
182
+
183
+ Extensions are defined with `ext` blocks, either inline in the Appendix
184
+ or in a shared `.mdl` file referenced by URI:
185
+
186
+ ```mdl
187
+ ext component
188
+ uri: org.dxos.mdl.component@1.0
189
+ desc: A UI component with props, state, slots, actions, and events.
190
+ fields:
191
+ props?: FieldMap
192
+ state?: FieldMap
193
+ slots?: FieldMap
194
+ actions?: ActionMap
195
+ emits?: EventMap
196
+ layout?: CodeBlock
197
+ ```
198
+
199
+ ### Extending Extensions
200
+
201
+ An extension may extend another, inheriting all its fields:
202
+
203
+ ```mdl
204
+ ext echo-type
205
+ uri: org.dxos/dxos/echo-type@1.0
206
+ extends: type
207
+ adds-fields:
208
+ echo-schema: TypeExpr
209
+ space?: SpaceRef
210
+ ```
211
+
212
+ ### Extension Inheritance
213
+
214
+ Specs compose via `extends` in frontmatter. The extension chain is transitive:
215
+ `Deus.DXOS` extends `Deus.Std` extends `Deus.Core`. A document inheriting
216
+ `Deus.DXOS` can use all constructs from all three layers without re-declaring them.
217
+
218
+ ## Standard Dialect (Deus.Std)
219
+
220
+ The standard dialect defines the common vocabulary for software specifications.
221
+ All constructs are `ext` declarations — there is no privileged status.
222
+
223
+ ### type
224
+
225
+ A named data structure with typed fields, variants, and invariants.
226
+
227
+ ```mdl
228
+ type Color
229
+ literals: white | black
230
+ ```
231
+
232
+ ```mdl
233
+ type Board
234
+ fields:
235
+ squares: Square[8][8]
236
+ turn: Color
237
+ status: playing | check | checkmate | stalemate
238
+ ```
239
+
240
+ ### op
241
+
242
+ A named operation with typed inputs, outputs, and declared errors.
243
+ Operations are either **pure** (no `effects`, no `requires`) or **effectful**.
244
+ This distinction maps directly to Effect-TS's `Effect<A, E, R>`.
245
+
246
+ ```mdl
247
+ op validateMove
248
+ desc: Checks a move against chess rules without mutating state.
249
+ input:
250
+ board: Board
251
+ move: Move
252
+ output: Move
253
+ errors:
254
+ IllegalMove: move violates chess rules
255
+ WrongTurn: piece does not belong to the active side
256
+ requires: [ChessEngine]
257
+ ```
258
+
259
+ ```mdl
260
+ op submitMove
261
+ desc: Validates and applies a move, then persists the updated Game.
262
+ input:
263
+ game: Game
264
+ player: Player
265
+ move: Move
266
+ output: Game
267
+ errors:
268
+ WrongTurn: player is not the active side
269
+ IllegalMove: move violates chess rules
270
+ GameOver: game has already ended
271
+ effects: [echo:write]
272
+ requires: [ChessEngine, GameStore]
273
+ ```
274
+
275
+ ### feat / req
276
+
277
+ Features group requirements. Requirements are atomic behavioural constraints,
278
+ written as prose or structured `when/then` blocks.
279
+
280
+ ```mdl
281
+ feat F-2: Make Move
282
+
283
+ req F-2.1:
284
+ when: player submits a Move on their turn
285
+ then: Move validated; Board updated; turn advances
286
+ errors: [InvalidMove, WrongTurn]
287
+ ```
288
+
289
+ ### scenario
290
+
291
+ Acceptance criteria expressed as Gherkin-style given / when / then steps. A scenario is a
292
+ _derivable_ criterion — the contract a vitest or storybook test is written against — and is
293
+ deliberately not the executable `test` of the QA dialect below. (Until 2026-09-08 this block was
294
+ named `test`; the rename freed the word for the runnable case.)
295
+
296
+ ```mdl
297
+ scenario T-6: Submit valid move
298
+ given: active game, white's turn
299
+ when: white submits pawn e2→e4
300
+ then:
301
+ - Board updated, e4 occupied
302
+ - Game.board.turn === black
303
+ - Game persisted to ECHO
304
+ ```
305
+
306
+ ### component
307
+
308
+ A UI component with props, internal state, named slots, actions, and emitted events.
309
+ Slots follow the `SlottableProps` pattern — named `ReactNode` injection points.
310
+
311
+ ```mdl
312
+ component Gameboard
313
+ props: { game: Game, playerId: string }
314
+ state: { selected?: Square, highlights: Square[] }
315
+ slots: { toolbar?: ReactNode, overlay?: ReactNode }
316
+ actions: { selectSquare(square: Square), submitMove(move: Move) }
317
+ emits: { onMove(move: Move), onResign() }
318
+ ```
319
+
320
+ ### service
321
+
322
+ An external or system-level dependency. Services are injected into `op` blocks
323
+ via `requires`. They may be local (WASM), remote (HTTP), or platform-provided (ECHO).
324
+
325
+ ```mdl
326
+ service ChessEngine
327
+ desc: Validates moves and computes game state. May be local (WASM) or remote.
328
+ loading: lazy
329
+ ops:
330
+ validate(board: Board, move: Move) → Move
331
+ legalMoves(board: Board, square: Square) → Square[]
332
+ ```
333
+
334
+ ### db
335
+
336
+ A persistence layer — schema, queries, and backend. In DXOS contexts the
337
+ backend is typically ECHO; the construct is general enough for SQL or any store.
338
+
339
+ ## QA Dialect (Deus.QA)
340
+
341
+ Defined in [`../lang/qa.mdl`](../lang/qa.mdl). Adds the executable half of a specification, with
342
+ vocabulary borrowed from xUnit so that a spec doubles as a test plan a human tester and an agent
343
+ tester execute from the same source:
344
+
345
+ | Term | Meaning |
346
+ | ----------- | ------------------------------------------------------------------------------- |
347
+ | `suite` | a named set of tests, selected by name or by tag; a container by reference |
348
+ | `test QA-n` | one executable case in three stages, `before` / `steps` / `after` |
349
+ | `step` | one move: a human `do`, an `expect` both actors judge, and usually one `invoke` |
350
+
351
+ `scenario` and `test` are deliberately distinct. A `scenario` is a _derivable_ criterion —
352
+ given/when/then, targeting vitest or a storybook play. A `test` is an _orchestrable_ script against
353
+ the running app: N ordered steps, each invoking at most one operation and each judged on its own
354
+ criterion.
355
+
356
+ ```mdl
357
+ test QA-1: Create and open a document
358
+ actors: both
359
+ covers: [F-1.1, T-1]
360
+ tags: [smoke]
361
+ given:
362
+ - space: a space is open
363
+ - collection: a collection in that space, to create into
364
+ steps:
365
+ - name: Create the document
366
+ do: In the navtree, click + on a collection and choose Markdown. Name it "QA: Notes $runId".
367
+ invoke: [op:createMarkdown] { name: "QA: Notes $runId", content: "# Notes\n" }
368
+ capture: created
369
+ expect: a Document named "QA: Notes $runId" is listed under the space, and no plank opens
370
+ assert: |
371
+ const rows = await composer.invoke('org.dxos.operation.space.queryObjects',
372
+ { typename: 'org.dxos.type.document' }, { spaceId: $given.space.id });
373
+ return rows.results.some((o) => o.dxn === $created.id) && $snapshot.planks.length === 0;
374
+ after:
375
+ - name: Delete it
376
+ do: Right-click the row and choose Delete.
377
+ invoke: org.dxos.operation.space.removeObjects { objects: [Obj($created.id)] }
378
+ expect: the row leaves the navtree
379
+ ```
380
+
381
+ Which runtime operation `[op:createMarkdown]` binds to decides what that `expect` may claim, which
382
+ is why `op@1.1` carries `key:`. `org.dxos.operation.markdown.create` persists the document and adds
383
+ it to the space's ROOT collection, so it is listed under the space — not under the `given`
384
+ collection, which it never reads. Its sibling `markdown.createDraft` is a true factory: it returns
385
+ a detached object, places nothing, and a step invoking it must assert on the return alone until a
386
+ later `space.addObject` places it. An `expect` written for one and run against the other fails for
387
+ a reason that has nothing to do with the application.
388
+
389
+ Steps are items of a stage list, not repeated `step <n>:` keys — core declares block bodies as
390
+ `key[?]: value` with an indented `-` list as the multi-line form, and a positional pseudo-key both
391
+ departs from that and forces hand-renumbering when a step is inserted. Numbering is by position;
392
+ a step needing a handle stable across insertions declares `id:`.
393
+
394
+ `do` and `expect` are required on every step — that is what keeps a test human-runnable, and a
395
+ step no human can perform is a design smell rather than a shortcut. `invoke` and `assert` are the
396
+ agent's affordances, and their absence is meaningful: a test containing a step with no operation
397
+ behind it (a drag, a reload, a judgement about flicker) cannot declare `actors: agent`.
398
+
399
+ The agent's eyes are the snapshot: after every step the runner calls
400
+ `org.dxos.operation.debug.snapshot` and binds the result as `$snapshot` for the step's `assert`, so
401
+ a test judges the app by its state — planks, spaces, toasts, errors since the run began — never by
402
+ an invocation's return value. A test that needs something the snapshot does not report extends the
403
+ snapshot operation rather than scripting the page.
404
+
405
+ Errors come in two bindings because the two uses pull opposite ways. `$snapshot.errors` is
406
+ cumulative from the run's start, which is what the report wants: an error is recorded against the
407
+ step where it first appeared. A pass/fail clause needs the opposite, so the runner also binds
408
+ `$stepErrors` — only what was logged since the previous step's snapshot. An `assert` written against
409
+ the cumulative array fails every step after the first background error, for something none of them
410
+ did.
411
+
412
+ A test runs in three stages — `before` (fixture), `steps` (the test), `after` (teardown) — so a
413
+ partial run is meaningful and a failure is legible: a `before` failure is a broken fixture, a
414
+ `steps` failure is a defect. Because each test owns its fixture and teardown, suites are
415
+ order-independent by construction and carry no `before` of their own.
416
+
417
+ Tests live in a `## QA` section of each `PLUGIN.mdl`, or in `spec/APP.mdl` of an application for
418
+ journeys crossing plugins. Agents execute them per the `composer-qa` skill through `/dxos:qa`; the
419
+ transport is the agent debug port.
420
+
421
+ Two consequences reach beyond the dialect:
422
+
423
+ - **`op` gains `key`** (`op@1.1`) — the runtime operation key. Without it a test cannot say which
424
+ operation it means, and the ambiguity is real: `plugin-markdown` declares one `op create` but
425
+ ships two runtime operations with different service requirements. The spec mirrors the code:
426
+ one `op` block per runtime key, with design-only operations marked `status: unimplemented`.
427
+ - **`requires` is informational, not a branch.** An operation's declaration cannot see the
428
+ services its downstream calls need, so a runner invokes everything through the operation invoker
429
+ with an explicit `spaceId` rather than deciding per step.
430
+
431
+ ## Changelog Dialect (Deus.Changelog)
432
+
433
+ Defined in [`../lang/changelog.mdl`](../lang/changelog.mdl). Adds a `## Changelog` section: an
434
+ append-only log of every decision that changed the spec. A reader can trace how the current text
435
+ came about, and which parts a person chose and which an agent filled in.
436
+
437
+ ```mdl
438
+ decision D-2: Bounds grow to the major grid. Fills in [D-1].
439
+ date: 2026-10-03
440
+ by: agent:claude-code
441
+ for: user:alice
442
+ affects: [Scene, F-2.1]
443
+ why: Growing to the minor grid re-lays the canvas on every drag step.
444
+ ```
445
+
446
+ - **Every change adds a decision.** `deus changelog check` enforces this in CI. It tolerates
447
+ trivial edits (whitespace, small typo fixes), and a `Spec-Changelog-Skip: <reason>` commit
448
+ trailer waives it for a bulk mechanical edit. It also rejects edits to existing entries: a
449
+ reversal is a new entry with `supersedes: D-n`.
450
+ - **One typed decider per entry.** `by:` is `user:<handle>` or `agent:<name>` (the harness, never
451
+ the model), and an `agent:` entry names its principal in `for:`.
452
+ - **The person's input is recorded faithfully, then the agent's additions.** The `user:` entry
453
+ restates what they said: references resolved, context included, wording fixed, but no
454
+ information added or removed. What the agent filled in is
455
+ in separate `agent:` entries. Approval of those entries is a later `user:` entry.
456
+ - **Open questions live in the log too.** A `question Q-n` records a choice nobody has made yet.
457
+ Answering it appends a `decision` with `answers: Q-n`, decided by whoever answered, so the
458
+ question stays append-only and "answered" is derived. Composer lists open questions above the
459
+ decisions and answers them in place.
460
+
461
+ ## Domain Dialects
462
+
463
+ ### Deus.DXOS
464
+
465
+ Extends `Deus.Std` with DXOS-specific constructs:
466
+
467
+ - **`echo-type`** — extends `type` with `echo-schema` and `space` fields
468
+ - **`composer-plugin`** — extends `service` with `surfaces` and `echo-types`
469
+ - **`effect-op`** — extends `op` with full Effect-TS dependency injection semantics
470
+
471
+ ## Round-Trip Development
472
+
473
+ ### Spec → Implementation
474
+
475
+ The `.mdl` file is the briefing an agent receives before writing code.
476
+ Structural blocks (`type`, `op`, `service`) map to TypeScript interfaces,
477
+ Effect functions, and service contracts. Behavioural blocks (`feat`, `req`)
478
+ are implementation constraints. Tests become vitest acceptance tests.
479
+
480
+ ### Implementation → Spec
481
+
482
+ When an agent modifies code, it compares the implementation against the spec
483
+ and proposes amendments as diffs to the `.mdl` file. This closes the loop:
484
+ the spec never goes stale, and drift is surfaced as a reviewable change.
485
+
486
+ ### Acceptance Criteria
487
+
488
+ `scenario` blocks are the contract between spec and verification. An agent
489
+ implementing a feature marks it complete only when the corresponding scenarios hold, in a unit
490
+ test or a QA `test` that `covers:` them. Scenarios can also be rendered as user-facing acceptance
491
+ criteria for review.
492
+
493
+ ## Tooling
494
+
495
+ ### Linter
496
+
497
+ A linter validates `.mdl` files against the declared extension schemas:
498
+
499
+ - Unknown block types → error
500
+ - Missing required fields → error
501
+ - Unresolved cross-references → error
502
+ - Unknown fields → warning
503
+ - Missing `scenario` or `test` coverage for `feat` blocks → warning
504
+
505
+ ### Renderers
506
+
507
+ A `.mdl` file can be rendered into multiple output formats:
508
+
509
+ - **FRS document** — structured Markdown requirements doc (like `FRS.md`)
510
+ - **Test stubs** — vitest `describe`/`test` scaffolding from `scenario` blocks
511
+ - **Type stubs** — TypeScript interfaces from `type` blocks
512
+ - **Ticket list** — `feat`/`req` blocks as linear/GitHub issues
513
+
514
+ ### CodeMirror Extension
515
+
516
+ The primary editor integration targets CodeMirror 6 (used inside the Composer plugin):
517
+
518
+ - **Lezer grammar** — parses block headers, body key-value pairs, type expressions
519
+ - **Syntax highlighting** — block type, identifier, field keys, type expressions
520
+ - **Lint integration** — inline errors and warnings from the linter
521
+ - **Completion** — field names and value enums from `ext` definitions
522
+ - **Hover** — shows the `ext` definition for any block type
523
+
524
+ DXOS already uses Lezer for the `echo-query` grammar; the same toolchain applies.
525
+
526
+ ### Composer Plugin
527
+
528
+ A dedicated Composer plugin provides a split editor/preview for `.mdl` files,
529
+ with the CodeMirror extension for editing and a rendered FRS view alongside.
530
+
531
+ ## Examples
532
+
533
+ The chess plugin trilogy demonstrates incremental spec evolution:
534
+
535
+ | File | New Extensions | What It Introduces |
536
+ | ------------- | -------------------------- | ----------------------------------------------- |
537
+ | `chess-1.mdl` | `type`, `feat`, `scenario` | Data model, game rules, acceptance criteria |
538
+ | `chess-2.mdl` | `component` | Lobby and Gameboard UI components |
539
+ | `chess-3.mdl` | `op`, `service` | Move validation, game persistence, chess engine |
540
+
541
+ See also `FRS.spec` in `plugin-spacetime` for a full real-world example.
542
+
543
+ ## Open Questions
544
+
545
+ - **`req` as standalone block vs. inline-only** — should requirements be
546
+ first-class blocks (addressable by ID anywhere) or only valid inside `feat`?
547
+ - **`db` vs `service`** — is a database just a service with a specific shape,
548
+ or does persistence deserve its own construct?
549
+ - **Registry** — what does the URI resolution registry look like in practice?
550
+ A JSON index? A git repo of `.mdl` files?
551
+ - **Versioning** — how are breaking changes to an extension handled?
552
+ Can a doc pin `type@1.0` while a sibling uses `type@2.0`?
553
+ - **Agent contract** — what is the precise interface between a Deus spec
554
+ and an implementing agent? A system prompt template? A tool schema?
555
+
556
+ ## Appendix
557
+
558
+ See [`../lang/core.mdl`](../lang/core.mdl) for the formal definition of the core
559
+ language and primitive types.
560
+ See [`../lang/examples/`](../lang/examples/) for the chess trilogy and the
561
+ spacetime plugin spec.