@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/lang/qa.mdl ADDED
@@ -0,0 +1,383 @@
1
+ ---
2
+ id: org.dxos.spec.qa
3
+ name: DSL.QA
4
+ version: 1.1
5
+ extends:
6
+ - org.dxos.spec.core
7
+ ---
8
+
9
+ The QA dialect. Adds the executable half of a specification, so a `.mdl` document doubles as a
10
+ test plan that a human tester and an agent tester execute from the same source.
11
+
12
+ The vocabulary is borrowed, not invented, and comes in two layers:
13
+
14
+ | Layer | Term | Meaning |
15
+ | --- | --- | --- |
16
+ | Gherkin — criteria, derivable | `feat` / `req` | a feature and its requirements |
17
+ | | `scenario T-n` | given / when / then; a criterion, not a script (Deus.Std) |
18
+ | xUnit — execution, runnable | `suite` | a named set of tests, selected by name or tag |
19
+ | | `test QA-n` | one executable case: `before` / `steps` / `after` |
20
+ | | `step` | one move: a human instruction and, usually, one operation |
21
+
22
+ A `test` is an ordered list of steps with a success criterion per step. Each step carries two
23
+ faces: a human instruction and, where the step maps to an invocable operation, an agent binding.
24
+ Neither face is a rendering of the other — a human clicks a navtree row, an agent invokes an
25
+ operation, and both are the truth about how that actor performs the step.
26
+
27
+ Tests live in a `## QA` section of a `PLUGIN.mdl`, or in `spec/APP.mdl` of an application for
28
+ journeys that cross plugins. Suites live beside the tests they group.
29
+
30
+ ## Extensions
31
+
32
+ | Term | URI |
33
+ | ------- | -------------------------- |
34
+ | `test` | `org.dxos.mdl.test@1.0` |
35
+ | `step` | `org.dxos.mdl.step@1.0` |
36
+ | `suite` | `org.dxos.mdl.suite@1.0` |
37
+ | `op` | `org.dxos.mdl.op@1.1` |
38
+
39
+ `org.dxos.mdl.test@1.0` named the given/when/then block until 2026-09-08; that block is now
40
+ `scenario` (`org.dxos.mdl.scenario@1.0`) and `test` is the executable one. A document declaring
41
+ `test` in its Extensions table means this definition.
42
+
43
+ ---
44
+
45
+ ## Relationship to `scenario`
46
+
47
+ `scenario` and `test` are not competitors and must not be collapsed:
48
+
49
+ | | `scenario T-n` | `test QA-n` |
50
+ |---|---|---|
51
+ | Kind | derivable criterion | orchestrable script |
52
+ | Shape | given / when / then | N ordered steps in three stages |
53
+ | Target | vitest, storybook play | the running app |
54
+ | Asserted by | the test runner | the human, or an agent through the debug port |
55
+
56
+ A test's `covers:` names the `feat` / `req` / `scenario` identifiers it exercises, so coverage is
57
+ a question the linter can answer rather than a guess.
58
+
59
+ ---
60
+
61
+ ## The `test` Block
62
+
63
+ ```mdl
64
+ ext test
65
+ uri: org.dxos.mdl.test@1.0
66
+ desc: |
67
+ An end-to-end case against the running application, executed by a human tester or an
68
+ agent. Three stages of ordered steps, each step with its own success criterion.
69
+ fields:
70
+ desc?: Prose
71
+ actors?: human | agent | both # default both; see the invoke rule below
72
+ covers?: RefList # feat / req / scenario ids this test exercises
73
+ status?: passing | failing | blocked | unverified # last known result, with a date in a comment
74
+ automated?: RefList # playwright specs that execute this test unattended (see below)
75
+ given?: GivenList # preconditions; `name: prose` binds `$given.name` (see below)
76
+ before?: StepList # fixture the test needs, but is not itself testing
77
+ steps: StepList # the test — the steps whose failure is a defect
78
+ after?: StepList # returning the app to its pre-test state
79
+ # all three are arrays of the same `step` shape
80
+ then?: ProseList # whole-test criteria, beyond the per-step ones
81
+ tags?: TagList
82
+ nesting: none
83
+ ```
84
+
85
+ ```mdl
86
+ ext step
87
+ uri: org.dxos.mdl.step@1.0
88
+ desc: |
89
+ One move in a test — an item of a stage list, not a block of its own. `do` and `expect`
90
+ are required: that is what keeps a test human-runnable, and a step no human can perform is a
91
+ design smell rather than a shortcut. A step invokes at most one operation.
92
+ fields:
93
+ name?: Prose # short title, for the report table
94
+ id?: Identifier # stable handle; see the numbering rule below
95
+ do: Prose # the human instruction (required)
96
+ expect: Prose # the success criterion BOTH actors judge (required)
97
+ invoke?: OpInvocation # operation key + input literal; one operation per step
98
+ space?: Expr # the space the invoker receives; default `$given.space`, else the default space
99
+ capture?: Identifier # names this step's result for later steps as `$<name>`
100
+ assert?: CodeBlock # deterministic check evaluated in the debug port; must return truthy
101
+ note?: Prose # a constraint the runner must respect (see Execution Rules)
102
+ blocked?: Prose # why this step cannot run at all, and what must change first
103
+ ```
104
+
105
+ Steps are items of a list, not repeated `step <n>:` keys. Core declares block bodies as
106
+ `key[?]: value`, with `key:` followed by an indented `-` list as the multi-line form — which
107
+ `given` already uses. A pseudo-key carrying a positional id is not core syntax, and
108
+ it forces every later step to be renumbered by hand when one is inserted.
109
+
110
+ ### Field rules
111
+
112
+ 1. **`do` and `expect` are required on every step.** A test whose steps only an agent can perform
113
+ is not a QA plan, it is a script.
114
+ 2. **`invoke` is optional, and its absence is meaningful.** A step with no operation behind it —
115
+ a drag, a page reload, a judgement about flicker — is a first-class step. A test containing any
116
+ such step cannot declare `actors: agent`.
117
+ 3. **`assert` is optional.** `expect` prose is always the criterion; `assert` only makes it
118
+ deterministic where that is cheap. Requiring it would make authoring a test a coding task.
119
+ 4. **`capture` threads a result forward** as `$<name>`, referenced in a later step's `invoke`.
120
+ Within a step, `$result` is that step's own `invoke` result, for use in its `assert`, and
121
+ `$<name>.snapshot` is the snapshot taken after that step, for an operation that returns less
122
+ than the step produced. Only serializable values cross a snippet boundary — an id does, a live
123
+ ECHO object does not (Rule 2).
124
+ 5. **`$snapshot` is the app's state after the step.** The runner takes one
125
+ `org.dxos.operation.debug.snapshot` after every step's `invoke` (or, for a step with none,
126
+ after the human reports it done) and binds it as `$snapshot` for the step's `assert`. It
127
+ carries `layout`, `planks`, `spaces`, `toasts`, `surfaces`, `attention`, `plugins`, and the
128
+ `errors` logged since the run started. A step judges the app by its snapshot or by a query
129
+ operation, never by the `invoke` return value (Rule 3). When a test needs something the snapshot
130
+ does not report, extend the snapshot operation rather than scripting the page.
131
+ Alongside it the runner binds **`$stepErrors`** — the entries of `$snapshot.errors` logged since
132
+ the previous step's snapshot, so this step's own errors and no one else's. `$snapshot.errors` is
133
+ cumulative by design (Rule 11) and therefore useless as a pass/fail clause: one background error
134
+ early in a run makes `$snapshot.errors.length === 0` false for every step after it. An `assert`
135
+ that judges errors uses `$stepErrors`; `$snapshot.errors` is for reporting.
136
+ 6. **A `given` entry written `name: prose` binds `$given.name`.** A bare entry is a condition to
137
+ check; a named one is also a value the runner must resolve and hold for the steps to reference
138
+ (`$given.collection`). Without this, a step's `invoke` would name something the test never
139
+ defined.
140
+ 7. **Steps are numbered by position**, from 1 within their stage, so `QA-1.3` is the third item
141
+ of `steps`. A step that needs a handle stable across insertions declares `id:`, and is then
142
+ referenced by it (`QA-1.open`) instead. Most steps do not need one; give an `id` to a step
143
+ whose failure is cited somewhere outside the document.
144
+
145
+ ### `automated` — the unattended arm of a test
146
+
147
+ A `test QA-n` is the specification of a journey; a Playwright spec is one *execution* of it, run
148
+ unattended on every CI cell. `automated:` names those specs, each entry
149
+ `<package>:<file>#<full test title>`:
150
+
151
+ ```mdl
152
+ automated:
153
+ - composer-e2e:basic.spec.ts#Basic tests › create document
154
+ ```
155
+
156
+ The binding is declared on **both** sides and checked, rather than left as prose:
157
+ `packages/e2e/composer-e2e/scripts/check-qa-coverage.mjs` reads every `automated:` here and every
158
+ `@QA` tag in the specs, and fails when either side names something the other does not have. A
159
+ one-sided link rots silently — a renamed test keeps a green check while the flow it claimed to
160
+ cover stops being exercised.
161
+
162
+ 1. **`automated` never replaces the steps.** The `do`/`expect` prose stays the contract, because a
163
+ spec asserts what it was written to assert and the flow is what a human re-runs when it breaks.
164
+ A test whose steps were deleted "because Playwright covers it" is no longer a QA flow.
165
+ 2. **The spec is free to cover a subset**, and usually does: `after` is teardown the runner does
166
+ not need when every worker gets a fresh profile, and a step with no operation behind it (a drag,
167
+ a reload) may be the whole reason a flow is `actors: human`. Coverage is a claim about the
168
+ `steps`, not about every stage.
169
+ 3. **A spec may name several flows** and a flow several specs; both sides are lists.
170
+ 4. **The check is referential, not semantic.** It proves the two sides name each other and that the
171
+ named test runs; it cannot read a Playwright spec and decide whether it exercises these `steps`.
172
+ A test tagged `@QA-n` that asserts nothing still passes the check, so the claim that a spec
173
+ covers a flow is a reviewer's judgement, not a verified fact. What the flow's own `assert`s
174
+ verify is the `composer-qa` run, which executes these steps against the live app; nothing
175
+ cross-checks the two arms against each other.
176
+
177
+ ### Input literals
178
+
179
+ An `invoke` is an operation key followed by a JSON-shaped input. Inside it:
180
+
181
+ | Form | Meaning | Snippet the runner emits |
182
+ | --- | --- | --- |
183
+ | `$name`, `$name.field`, `$name.snapshot.…` | a captured result or a `given` binding; any JS path over it | the held value |
184
+ | `$runId` | this run's id, so artifacts are attributable | the string |
185
+ | `Obj("echo://S/O")` | the live object at that URI | `dxos.spaces('S').db.getObjectById('O')` |
186
+ | `Ref("echo://S/O")` | a reference to it, for `Ref` inputs | `dxos.Ref.make(…getObjectById('O'))` |
187
+ | `Space("S")` | the live space, for `space` inputs | `dxos.spaces('S')` |
188
+
189
+ Placeholders may appear inside strings (`"QA: Basics $runId"`, `"root/$given.space.id/…"`). A
190
+ `create` operation returns a URI, not an object, precisely so that a later step can name the
191
+ object through `Obj(…)` after a snippet boundary. A held value that is an `echo://` URI also
192
+ exposes `.spaceId` and `.objectId`, parsed by the runner, so a navigation path is written
193
+ `"root/$space.id/content/collections/$doc.objectId"` without a step to split the URI.
194
+
195
+ ### Operation references
196
+
197
+ Within the document, an operation declared here is referenced as `[op:<id>]`, which resolves via
198
+ that block's `key:` field (`op@1.1`).
199
+
200
+ An operation owned by **another** plugin is written as a full key literal. This is not only an
201
+ `APP.mdl` concern: a plugin-scoped test routinely drives `space.addObject` and `appToolkit.open`,
202
+ and neither is declared in the plugin's own spec.
203
+
204
+ ---
205
+
206
+ ## The `suite` Block
207
+
208
+ ```mdl
209
+ ext suite
210
+ uri: org.dxos.mdl.suite@1.0
211
+ desc: |
212
+ A named set of tests, run together and reported together. A container by reference: the
213
+ tests stay standalone blocks, and a suite lists them by id — `QA-1` for a test in the same
214
+ document, `markdown:QA-1` for another plugin's (`app:QA-1` for the application spec).
215
+ fields:
216
+ desc?: Prose
217
+ tags?: TagList # `run --tag nightly` selects every suite carrying the tag
218
+ tests: RefList # ordered for the report; execution is order-independent
219
+ nesting: none
220
+ ```
221
+
222
+ 1. **Suites are order-independent by construction.** Every test owns its fixture (`given` +
223
+ `before`) and its teardown (`after`), so any selection of tests is runnable in any order. There
224
+ is no suite-level `before`: anything every member needs — a plugin enabled, an identity — goes in
225
+ each test's `given`, which the runner establishes idempotently.
226
+ 2. **Every document is an implicit suite** of its own tests, addressed by its short name
227
+ (`run markdown`), so a plugin needs no `suite` block to be runnable as a unit.
228
+ 3. **Tags select suites, not tests.** `run --tag nightly` runs the union of the tests of every
229
+ suite tagged `nightly`, de-duplicated. A test's own `tags:` are descriptive and searchable but
230
+ do not put it in a run.
231
+
232
+ ---
233
+
234
+ ## `op@1.1` — the `key` field
235
+
236
+ ```mdl
237
+ ext op
238
+ uri: org.dxos.mdl.op@1.1
239
+ extends: op
240
+ adds-fields:
241
+ key?: NSID # runtime operation key — what the invoker receives
242
+ ```
243
+
244
+ Without `key`, a test cannot say which operation it means. The distinction is real and not
245
+ academic: `plugin-markdown` declares one `op create` but ships two runtime operations —
246
+ `org.dxos.operation.markdown.create` (agent-facing, `Database.Service`) and
247
+ `org.dxos.operation.markdown.createDraft` (the UI factory, `Capability.Service`). A test that
248
+ guesses picks the wrong one and fails at runtime.
249
+
250
+ The spec mirrors the code: one `op` block per runtime `Operation.make` key, with `key:` and
251
+ `requires:` copied from its `meta.key` and `services`. A design-level operation with no runtime
252
+ counterpart keeps its block without `key:` and says so in `status: unimplemented`, so a reader can
253
+ tell an intended operation from an existing one and a test never references it.
254
+
255
+ Populate the pre-existing `requires:` from the code's `services:` at the same time. It is
256
+ informational — see Execution Rule 1 — but it tells a reader why a step behaves as it does.
257
+
258
+ ---
259
+
260
+ ## Execution Rules
261
+
262
+ These are not style advice. Each was established by running a test against a live application;
263
+ a runner that ignores them produces false failures.
264
+
265
+ 1. **Always invoke through the operation invoker with an explicit `spaceId`.** Do not branch on
266
+ `requires:`. An operation's own declaration cannot see the services its *downstream* calls
267
+ need, so `requires:` is necessary but not sufficient to predict whether a plain invoke will
268
+ work. Taking the invoker path unconditionally removes the question. The step's `space:` names
269
+ the space; absent, `$given.space`, else the default space.
270
+
271
+ 2. **Coalesce adjacent steps that thread a live object.** The debug port serializes between
272
+ snippets, so an ECHO object captured in one step cannot be passed to the next. Human step
273
+ granularity and snippet granularity are different things, and reconciling them is the runner's
274
+ job, not the author's. Prefer captures that are strings (a URI, an id, a path) and `Obj(…)` in
275
+ the next step, which needs no coalescing at all.
276
+
277
+ 3. **Verify the effect, never the return value.** A successful invocation frequently did less
278
+ than the step intended — a `create` operation is a factory and places nothing. Judge `expect`
279
+ against `$snapshot`, a query operation, or the DOM.
280
+
281
+ 4. **Establish `given` or abort.** A test that runs against unmet preconditions reports failures
282
+ that belong to the fixture, not the application.
283
+
284
+ 5. **Assertions must be falsifiable against a dirty fixture.** An existence-shaped check
285
+ (`some((o) => o.name === 'Notes')`) is already true when a previous run left its artifacts
286
+ behind, so the step reports pass having done nothing. Assert on the identity the test just
287
+ produced (`o.id === $created.object.id`), and name the test's own artifacts in `given` as
288
+ preconditions of their absence. Artifacts carry the `QA:` prefix and `$runId` in their name.
289
+
290
+ 6. **Resolve an operation by its exact key, never by suffix.** `endsWith('create')` matches both
291
+ `org.dxos.operation.markdown.create` and `org.dxos.operation.markdown.createDraft` — the very
292
+ ambiguity `key:` exists to remove.
293
+
294
+ 7. **Three stages, run in order: `before`, `steps`, `after` — each an array of the same `step`.**
295
+ Put a step in `before` only when it is fixture the test is not itself exercising. Creating the
296
+ subject usually IS the test: QA-2 tests that two documents can be made and linked, so the
297
+ creating belongs in `steps`, and `before` stays empty. `before` builds the fixture,
298
+ `steps` is the test, `after` undoes it. The split is what makes a partial run meaningful — and
299
+ what makes a failure legible, since a `before` failure is a broken fixture while a `steps`
300
+ failure is a defect in the application. Every stage is a step list; `after` in particular is
301
+ steps, not prose, and goes through operations like any other. A prose instruction ("delete the
302
+ document") leaves each actor to pick a mechanism, and they diverge: a human uses the navtree's
303
+ delete action, which routes through `space.removeObjects` and closes any open plank; a runner
304
+ reaching for `space.db.remove` strands a plank pointing at an object that no longer exists,
305
+ which the user cannot then close. `after` removes only what this run created, by identity.
306
+
307
+ 8. **A partial run is the runner's option, not the test's.** A test always declares all three
308
+ stages; which of them to run is decided per invocation. Running `before` alone stands a fixture
309
+ up to look at; `after` alone tears one down; `steps` alone re-tests against a fixture already
310
+ standing. Whatever is skipped must be reported — what remains and how to remove it — since the
311
+ next full run's `given` will otherwise fail on its own leftovers (Rule 5).
312
+
313
+ 9. **A step that cannot run says so in `blocked`, and the test's `status` becomes `blocked`.**
314
+ Not `failing` — nothing was tested — and not silence, which reads as untried. A duplicate
315
+ operation key, a missing capability or a removed operation all land here.
316
+
317
+ 10. **Report by test and step number** — `QA-1.3`, or `QA-1.<id>` for a step declaring one — so a
318
+ failure is addressable without prose. Prefer the id where a step has one: it survives a step
319
+ being inserted ahead of it, a position does not.
320
+
321
+ 11. **Snapshot after every step, and `errors` is always a finding.** The runner passes the run's
322
+ start time as `since`, so each snapshot reports every error logged so far; a non-empty
323
+ `errors` fails nothing by itself but is recorded against the step where it first appeared,
324
+ even when that step's own check passed. A step that means to fail on an error asserts on
325
+ `$stepErrors` (Field rule 5), never on `$snapshot.errors`: the cumulative array keeps one early
326
+ background error false for the rest of the run, which reads as every later step failing for
327
+ something none of them did. Both smoke runs of `app:QA-1` hit exactly that.
328
+
329
+ 12. **A suite run continues past a failed test.** Each test is self-contained, so a failure in
330
+ one — including a failed `after` — is reported and the next test's `given` guards it. A run
331
+ stops early only when the app itself is gone: the port no longer answers, or the page has
332
+ crashed.
333
+
334
+ ---
335
+
336
+ ## Example
337
+
338
+ ```mdl
339
+ test QA-1: Create a space and a document, then delete the document
340
+ actors: both
341
+ covers: [F-1.1, T-1]
342
+ tags: [smoke]
343
+ given:
344
+ - an identity exists and the default space is SPACE_READY
345
+ - no space whose name starts with "QA:" exists — ABORT rather than deleting one this test did not create
346
+ before:
347
+ - name: Create a space
348
+ do: Open the space list's +, name the space "QA: Basics $runId" and create it.
349
+ invoke: org.dxos.operation.space.create { name: "QA: Basics $runId" }
350
+ capture: space
351
+ expect: the navtree switches to the new space
352
+ assert: return $snapshot.spaces.some((s) => s.id === $space.id && s.state === 'SPACE_READY')
353
+ steps:
354
+ - name: Create a document
355
+ do: With the new space selected, click + and choose Document. Name it "QA: Doc 1".
356
+ invoke: org.dxos.operation.markdown.create { name: "QA: Doc 1", content: "# QA: Doc 1\n" }
357
+ space: $space.id
358
+ capture: doc
359
+ expect: "QA: Doc 1" appears as a row under the space
360
+ assert: |
361
+ const docs = await composer.invoke('org.dxos.operation.space.queryObjects',
362
+ { typename: 'org.dxos.type.document' }, { spaceId: $space.id });
363
+ return docs.some((o) => o.id === $doc.id);
364
+ - name: Delete it
365
+ do: Open the row's ⋮ menu and choose Delete.
366
+ invoke: org.dxos.operation.space.removeObjects { objects: [Obj($doc.id)] }
367
+ space: $space.id
368
+ expect: a "Document deleted" toast with Undo appears and the row is gone
369
+ assert: return $snapshot.toasts.some((t) => t.title === 'Document deleted') && $stepErrors.length === 0
370
+ after:
371
+ - name: Delete the space
372
+ do: Open the space's settings and delete the space; pick the default space.
373
+ invoke: org.dxos.operation.space.delete { space: Space($space.id) }
374
+ expect: no "QA:" space remains and the workspace is the default space
375
+ assert: return !$snapshot.spaces.some((s) => s.name?.startsWith('QA:'))
376
+ ```
377
+
378
+ ```mdl
379
+ suite smoke: Boots, one space, one document
380
+ desc: The five-minute check a Routine runs on every merge to main.
381
+ tags: [smoke, nightly]
382
+ tests: [QA-1]
383
+ ```
@@ -0,0 +1,103 @@
1
+ ---
2
+ id: org.dxos.spec.review
3
+ name: DSL.Review
4
+ version: 1.0
5
+ extends:
6
+ - org.dxos.spec.core
7
+ ---
8
+
9
+ The review dialect. A review is a separate document that judges how far the code meets a spec, item
10
+ by item. It is written by an agent (the `spec-review` skill) or a person, and lives beside the spec
11
+ it judges: `PLUGIN.mdl` → `PLUGIN.review.mdl`. Each new review replaces the previous file; git keeps
12
+ the history. The spec viewer reads the latest review and marks each judged item with its status.
13
+
14
+ A review is evidence, not a decision: it never changes the spec, and it adds no changelog entry.
15
+
16
+ ## Extensions
17
+
18
+ | Term | URI |
19
+ | --------- | --------------------------- |
20
+ | `verdict` | `org.dxos.mdl.verdict@1.0` |
21
+
22
+ ## Document
23
+
24
+ Frontmatter names what was reviewed and against what:
25
+
26
+ ```yaml
27
+ ---
28
+ spec: github:dxos/dxos/packages/plugins/plugin-file-system/PLUGIN.mdl
29
+ commit: 64dcf3f44a541fdf0b3e55803f38d214e76a6279 # the code the review read
30
+ date: 2026-10-22
31
+ by: agent:claude-code # same actor forms as the changelog
32
+ ---
33
+ ```
34
+
35
+ The body opens with a short summary, then one `verdict` per reviewed item.
36
+
37
+ ## Statuses
38
+
39
+ | Status | Meaning |
40
+ | ---------- | ------------------------------------------------------------------------ |
41
+ | `done` | The code does what the item says. |
42
+ | `untested` | The code does it, but no test exercises it. |
43
+ | `partial` | Some of what the item says is done; the note says which part is not. |
44
+ | `diverged` | The code does something different from what the item says. |
45
+ | `missing` | Nothing in the code does it. |
46
+
47
+ The spec viewer shows beside each judged item whether code covers it (its `evidence:`, or "no code")
48
+ and whether tests exercise it: `tested` when the verdict names `tests:` or is `done`, `untested` for
49
+ any other status but `missing`, where there is no code to test.
50
+
51
+ ## Tests and scenarios
52
+
53
+ A `scenario` or a `test` block describes behaviour to exercise, so it is judged on whether
54
+ automation exercises it, not on whether code implements it:
55
+
56
+ | Status | For a `scenario` or `test` |
57
+ | ---------- | --------------------------------------------------------------------------- |
58
+ | `done` | An automated test runs it end to end; `tests:` cites that test. |
59
+ | `partial` | A test covers some of its steps or `then:` clauses; the note says which. |
60
+ | `diverged` | A test runs something different from what it describes. |
61
+ | `missing` | Nothing runs it (a manual QA run is not automation). |
62
+
63
+ `untested` does not apply. `tests:` names the test files that exercise it and is required for
64
+ `done`, `partial` and `diverged`; `evidence:` may name the code it drives. The viewer shows
65
+ `tested`, `partly tested` or `not tested` beside it, with a chip per test file.
66
+
67
+ ## Walkthrough
68
+
69
+ When an item is implemented in more than one place, the verdict carries a `walkthrough:`: 1 to 5
70
+ segments, in reading order, that say where each part is implemented. Each segment is one
71
+ sentence followed by the `github:` key of the code it describes; the viewer shows the sentence
72
+ above the declaration the key names, linked to its file. Keep each sentence to what the code
73
+ does for this item, not how it works line by line.
74
+
75
+ - A `type` needs none: its one declaration is the hover card of its code chip.
76
+ - An `op` walks its declaration (the schema), then each handler.
77
+ - A `feat` or `req` walks the pieces in the order a request passes through them.
78
+
79
+ An item with a single implementation gets no walkthrough.
80
+
81
+ A `feat` with nested `req` items is judged through its requirements; its status is the worst of
82
+ theirs. Judge a `feat` directly only when it has no requirements.
83
+
84
+ ## Definitions
85
+
86
+ ```mdl
87
+ ext verdict
88
+ uri: org.dxos.mdl.verdict@1.0
89
+ desc: |
90
+ How far the code meets one spec item. The identifier is the item's id in the reviewed spec
91
+ (`F-1.2`, `Scene`, `openDirectory`); the inline prose is the verdict in one line.
92
+ fields:
93
+ status: done | untested | partial | diverged | missing
94
+ evidence?: RefList # github: keys of the code that supports the verdict, with #Symbol
95
+ tests?: RefList # github: keys of the test files that exercise the item, without #
96
+ walkthrough?: ProseList # 1-5 items `- <one sentence>. github:<key>`, when there is more than one implementation
97
+ note?: Prose # what is missing or different; required unless status is done
98
+ syntax: |
99
+ verdict F-1.2: The picker opens on the action.
100
+ status: done
101
+ evidence: [github:dxos/dxos/packages/plugins/plugin-file-system/src/util.ts#openDirectoryPicker]
102
+ tests: [github:dxos/dxos/packages/plugins/plugin-file-system/src/util.test.ts]
103
+ ```
package/lang/sql.mdl ADDED
@@ -0,0 +1,72 @@
1
+ ---
2
+ id: org.dxos.spec.sql
3
+ name: DSL.Sql
4
+ version: 1.0
5
+ extends:
6
+ - org.dxos.spec.core
7
+ ---
8
+
9
+ The SQL dialect: one `table` block that declares a SQL table a component owns — its columns, key,
10
+ indexes, and the migration set that creates it. Before this dialect a spec named its tables only in
11
+ prose ("a new migration adds the column"), so a reviewer could not see the schema a requirement
12
+ relies on, and a spec review could not judge it.
13
+
14
+ A `table` block states the schema as it is after the spec's changes, not the history: the history is
15
+ the numbered migrations in the code, and the reasons are in the changelog. Use `type` for an ECHO
16
+ schema; a `table` is a store-level SQL table that is not an ECHO object.
17
+
18
+ ## Extensions
19
+
20
+ | Term | URI |
21
+ | ------- | ------------------------- |
22
+ | `table` | `org.dxos.mdl.table@1.0` |
23
+
24
+ ## Model
25
+
26
+ - **The identifier is the table name**, exactly as in the DDL (`feeds`, `convergenceKeyIntents`).
27
+ The inline prose says what one row is.
28
+ - **`columns:`** has one line per column: `name: SQLTYPE [constraint …] # meaning`.
29
+ - `SQLTYPE` is a SQLite storage class: `INTEGER`, `REAL`, `TEXT` or `BLOB`. A column that holds
30
+ JSON is `TEXT` with `json` in its comment and the TypeScript type it decodes to.
31
+ - A trailing `?` on the name means `NULL` is allowed (`feedNamespace?: TEXT`); without it the
32
+ column is `NOT NULL`.
33
+ - Constraints are written as in SQL: `PRIMARY KEY`, `AUTOINCREMENT`, `UNIQUE`, `DEFAULT <value>`,
34
+ `REFERENCES <table>(<column>)`.
35
+ - **`key:`** names the primary key, and `unique:` any other unique keys, as column lists.
36
+ - **`indexes:`** has one line per secondary index: `name(columns)` and why a query needs it.
37
+ - **`store:`** names the database the table lives in and, in parentheses, its migration-history table
38
+ (`feed store (feed_migrations)`), so the reader knows which migrations change it. A spec names
39
+ components and specs, never file paths: the code moves, the names stay.
40
+ - **`new:`** marks a table or columns the spec adds: `table` for a new table, or the list of new
41
+ columns. A spec review checks that a migration adds each of them.
42
+ - A `table` is a spec item: a requirement cites it as `table:feeds` or a column as
43
+ `table:feeds.options`, a review can judge it (`verdict table:feeds`), and a `github:` key may
44
+ point at the migration that creates it.
45
+
46
+ ## Definitions
47
+
48
+ ```mdl
49
+ ext table
50
+ uri: org.dxos.mdl.table@1.0
51
+ desc: |
52
+ A SQL table a component owns. The identifier is the table name; the inline prose is what one row
53
+ is. Columns, keys and indexes are the schema after the spec's changes.
54
+ fields:
55
+ store: Prose # the database, and its migration-history table in parentheses
56
+ columns: FieldMap # `name[?]: SQLTYPE [constraint …] # meaning`; `?` allows NULL
57
+ key?: Prose # the primary key, as a column list
58
+ unique?: ProseList # other unique keys, as column lists
59
+ indexes?: ProseList # `name(columns): why a query needs it`
60
+ new?: Prose # `table`, or the columns this spec adds
61
+ inline-prose: true
62
+ syntax: |
63
+ table feeds: One feed of a space, by namespace.
64
+ store: feed store (feed_migrations)
65
+ columns:
66
+ feedPrivateId: INTEGER PRIMARY KEY AUTOINCREMENT # local row id; blocks reference it
67
+ spaceId: TEXT
68
+ feedId: TEXT # the Feed object's entity id
69
+ options?: TEXT # json FeedOptions; NULL = defaults
70
+ key: feedPrivateId
71
+ new: options
72
+ ```
package/package.json CHANGED
@@ -1,6 +1,77 @@
1
1
  {
2
2
  "name": "@dxos/deus",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.0",
4
+ "description": "Deus — pattern specification language for human-agent collaborative software development. Carries the .mdl grammar, CodeMirror extension, and core dialects.",
5
+ "homepage": "https://dxos.org",
6
+ "bugs": "https://github.com/dxos/dxos/issues",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/dxos/dxos"
10
+ },
11
+ "license": "FSL-1.1-Apache-2.0",
12
+ "author": "info@dxos.org",
13
+ "sideEffects": false,
14
+ "type": "module",
15
+ "exports": {
16
+ ".": {
17
+ "source": "./src/index.ts",
18
+ "types": "./dist/types/src/index.d.ts",
19
+ "import": "./dist/lib/index.mjs"
20
+ },
21
+ "./extension": {
22
+ "source": "./src/extension/index.ts",
23
+ "types": "./dist/types/src/extension/index.d.ts",
24
+ "import": "./dist/lib/extension.mjs"
25
+ },
26
+ "./parse": {
27
+ "source": "./src/extension/parse.ts",
28
+ "types": "./dist/types/src/extension/parse.d.ts",
29
+ "import": "./dist/lib/parse.mjs"
30
+ },
31
+ "./review": {
32
+ "source": "./src/review/index.ts",
33
+ "types": "./dist/types/src/review/index.d.ts",
34
+ "import": "./dist/lib/review.mjs"
35
+ },
36
+ "./spec-index": {
37
+ "source": "./src/spec-index/index.ts",
38
+ "types": "./dist/types/src/spec-index/index.d.ts",
39
+ "import": "./dist/lib/spec-index.mjs"
40
+ },
41
+ "./cli": {
42
+ "source": "./src/cli/index.ts",
43
+ "types": "./dist/types/src/cli/index.d.ts",
44
+ "import": "./dist/lib/cli.mjs"
45
+ }
46
+ },
47
+ "bin": {
48
+ "deus": "./bin/deus.ts"
49
+ },
50
+ "files": [
51
+ "bin",
52
+ "dist",
53
+ "docs",
54
+ "lang",
55
+ "src"
56
+ ],
57
+ "dependencies": {
58
+ "@codemirror/autocomplete": "^6.20.3",
59
+ "@codemirror/language": "^6.12.4",
60
+ "@codemirror/lint": "6.9.7",
61
+ "@codemirror/state": "^6.7.6",
62
+ "@codemirror/view": "^6.43.13",
63
+ "@effect/platform-node": "4.0.4",
64
+ "@lezer/highlight": "^1.2.3",
65
+ "@lezer/lr": "^1.4.10",
66
+ "effect": "4.0.4",
67
+ "@dxos/errors": "0.16.0"
68
+ },
69
+ "devDependencies": {
70
+ "@lezer/generator": "^1.8.0",
71
+ "typescript": "^7.0.2",
72
+ "vitest": "4.1.10"
73
+ },
74
+ "publishConfig": {
75
+ "access": "public"
76
+ }
6
77
  }
@@ -0,0 +1,13 @@
1
+ ---
2
+ id: org.dxos.fixture.bad-decision
3
+ name: Bad decision
4
+ version: 0.1.0
5
+ ---
6
+
7
+ ## Changelog
8
+
9
+ ```mdl
10
+ decision D-1: An agent decision that names nobody it acted for.
11
+ date: 2026-10-23
12
+ by: agent:claude-code
13
+ ```