@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
@@ -0,0 +1,184 @@
1
+ ---
2
+ id: org.dxos.spec.changelog
3
+ name: DSL.Changelog
4
+ version: 1.0
5
+ extends:
6
+ - org.dxos.spec.core
7
+ ---
8
+
9
+ The changelog dialect. Adds a `## Changelog` section to a spec: an append-only log of every
10
+ decision that changed it, each one attributed to the person or the agent that made it. The body of
11
+ a spec says what is true now; the changelog says who decided it, when, and why.
12
+
13
+ A spec is written by people and agents together. Typically the person gives coarse direction and
14
+ the agent fills in the gaps. The two carry different authority, so the log keeps their knowledge
15
+ in separate entries: every entry names exactly one decider, typed as `user:` or `agent:`, and
16
+ "which parts of this spec did a person choose?" is a filter, not an archaeology project.
17
+
18
+ ## Extensions
19
+
20
+ | Term | URI |
21
+ | ---------- | ---------------------------- |
22
+ | `decision` | `org.dxos.mdl.decision@1.0` |
23
+ | `question` | `org.dxos.mdl.question@1.0` |
24
+
25
+ ## Actors
26
+
27
+ Every actor reference carries one of two prefixes. The prefix is the point of the dialect: the
28
+ linter rejects a `by:` without one.
29
+
30
+ | Form | Who | Example |
31
+ | ----------------- | ----------------------------------------------------- | ----------------------------- |
32
+ | `user:<handle>` | A person, by GitHub username or email. | `user:alice`, `user:a@b.org` |
33
+ | `agent:<name>` | An agent, by harness or product name — never a model. | `agent:claude-code` |
34
+
35
+ Name an agent by what ran it (`agent:claude-code`, `agent:composer-assistant`), not by the model
36
+ that served it: models change mid-session and the name must stay stable across the log.
37
+
38
+ ## Rules
39
+
40
+ 1. **Every change to a spec adds a decision.** A change to anything outside `## Changelog` comes
41
+ with at least one new entry in the same change. The check
42
+ `pnpm deus changelog check` enforces this in CI. Trivial edits are exempt:
43
+ whitespace, and fixes of at most 3 words by 1–2 letters each, excluding words with digits and
44
+ normative words. A bulk mechanical edit, or a change with no spec decision behind it (rule 9),
45
+ may be waived with a `Spec-Changelog-Skip: <reason>` commit trailer.
46
+ 2. **One decider per entry.** An entry is `by:` exactly one `user:` or `agent:`. Knowledge from
47
+ two sources is two entries, even when they land in the same edit.
48
+ 3. **A person's input is recorded faithfully, first.** When a person gives direction, the first
49
+ entry is `by: user:<them>` and restates what they said in spec terms. The recording agent may
50
+ resolve references ("it", "the canvas" → `Scene`), include the context needed to read the entry
51
+ on its own, and fix wording. It must not add or remove information: no requirement, rationale or
52
+ assumption the person did not give, and nothing they said left out. Prompts are messy, so the
53
+ entry is a clean statement of their intent, not a transcript. The decider is who chose, not who
54
+ typed: an agent writes this entry, the person made it.
55
+ 4. **What the agent adds is a separate entry.** Gaps the agent filled — shapes, names, edge cases,
56
+ a reading of an ambiguous instruction — go in later `by: agent:<name>` entries, one per
57
+ independent choice, referring to the entry they build on (`Fills in [D-1]`).
58
+ 5. **An agent entry names its principal.** `for:` is the person whose instruction the agent was
59
+ acting under. It is required on `agent:` entries and forbidden on `user:` entries.
60
+ 6. **Approval is a decision.** A person who reviews and accepts agent entries makes a new
61
+ `user:` entry saying so ("Approve [D-2] and [D-3]."). Nothing in the approved entry changes.
62
+ 7. **Append-only.** Never edit or delete an entry. To reverse or refine one, append a new entry
63
+ with `supersedes: D-n`. The superseded entry stays — it is the trace.
64
+ 8. **Identifiers are monotonic, newest last.** `D-1`, `D-2`, … in the order appended. Never reuse
65
+ or renumber.
66
+ 9. **Only spec decisions.** An entry records a choice about the specified system: its behavior,
67
+ requirements, structure, interfaces, data, tests, or the reason for one of those. How the authors
68
+ worked is not a decision: which tool or skill they used, how the spec is shared or reviewed, which
69
+ PR a change goes in, that the document exists, has diagrams, or was reorganized. When a person's
70
+ instruction is only about process, follow it and record nothing. A spec change with no decision
71
+ behind it carries the `Spec-Changelog-Skip` trailer instead. `.agents/skills/mdl/scripts/check-decisions.ts` checks
72
+ new entries with TypeSafe System One.
73
+ 10. **An open question is a `question`, and its answer is a decision.** A choice the spec needs but
74
+ nobody has made yet goes in `## Changelog` as `question Q-n`, attributed like a decision. It is
75
+ answered by appending a `decision` whose `answers:` names it; the decider is whoever answered.
76
+ The question itself is never edited, so "answered" is derived, not stored. Only the first
77
+ decision that answers a question counts; to change the answer, supersede that decision.
78
+ Question ids are `Q-1`, `Q-2`, … in the order asked, a sequence of their own.
79
+
80
+ ## Definitions
81
+
82
+ ```mdl
83
+ ext decision
84
+ uri: org.dxos.mdl.decision@1.0
85
+ desc: |
86
+ One decision about the spec, attributed to exactly one actor. The inline prose is the decision
87
+ itself, stated as what is now true ("Bounds are derived, never stored."), not as the edit
88
+ that was made.
89
+ fields:
90
+ date: Date # YYYY-MM-DD, the day the decision was made
91
+ by: ActorRef # user:<handle> | agent:<name> — the decider
92
+ for?: UserRef # agent entries only: the person the agent acted for
93
+ affects?: RefList # block ids the decision constrains, e.g. [Scene, F-2.1]
94
+ supersedes?: Identifier # an earlier decision this one replaces
95
+ why?: Prose # the reason; on a user entry, only a reason the person gave
96
+ rejected?: ProseList # alternatives considered and why they lost
97
+ source?: URI # PR, review comment, issue, or session where it was made
98
+ answers?: Identifier # a question this decision answers, e.g. Q-1
99
+ inline-prose: true
100
+ ```
101
+
102
+ ```mdl
103
+ ext question
104
+ uri: org.dxos.mdl.question@1.0
105
+ desc: |
106
+ A choice the spec needs that nobody has made yet, attributed to the actor that asked it. The
107
+ inline prose is the question. It is answered by a later `decision` whose `answers:` names it.
108
+ fields:
109
+ date: Date # YYYY-MM-DD, the day it was asked
110
+ by: ActorRef # user:<handle> | agent:<name> — who asked
111
+ for?: UserRef # agent questions only: the person the agent acted for
112
+ affects?: RefList # block ids the answer will constrain
113
+ context?: Prose # why it is asked, and what depends on the answer
114
+ options?: ProseList # suggested answers, each `<title>: <description>`
115
+ source?: URI # PR, review comment, issue, or session where it was asked
116
+ inline-prose: true
117
+ ```
118
+
119
+ ## Example
120
+
121
+ A person asks for a feature in one line; the agent records it, then fills it in; the person
122
+ approves part of it and overrides the rest.
123
+
124
+ ```mdl
125
+ decision D-1: The `Scene` canvas grows to fit its content when a node moves past its edge.
126
+ date: 2026-10-02
127
+ by: user:alice
128
+ affects: [Scene]
129
+ source: https://github.com/dxos/dxos/pull/<n>
130
+ ```
131
+
132
+ ```mdl
133
+ decision D-2: Bounds are derived from content, never stored. Fills in [D-1].
134
+ date: 2026-10-02
135
+ by: agent:claude-code
136
+ for: user:alice
137
+ affects: [Scene]
138
+ why: Stored bounds drift from the content whenever a node moves outside an edit path.
139
+ ```
140
+
141
+ ```mdl
142
+ decision D-3: Bounds grow to the major grid. Fills in [D-1].
143
+ date: 2026-10-02
144
+ by: agent:claude-code
145
+ for: user:alice
146
+ affects: [Scene, F-2.1]
147
+ why: Growing to the minor grid re-lays the canvas on every drag step.
148
+ rejected:
149
+ - Fixed padding: clips large nodes at the edge.
150
+ ```
151
+
152
+ ```mdl
153
+ decision D-4: Approve [D-2].
154
+ date: 2026-10-05
155
+ by: user:alice
156
+ ```
157
+
158
+ ```mdl
159
+ decision D-5: Bounds grow to the minor grid while dragging and snap to the major grid on drop, because growing to the major grid feels laggy.
160
+ date: 2026-10-05
161
+ by: user:alice
162
+ supersedes: D-3
163
+ ```
164
+
165
+ The agent meets a choice it should not make alone, and asks; the person's answer is a decision.
166
+
167
+ ```mdl
168
+ question Q-1: Does the canvas shrink when nodes are removed?
169
+ date: 2026-10-06
170
+ by: agent:claude-code
171
+ for: user:alice
172
+ affects: [Scene]
173
+ context: [D-1] grows the bounds; nothing says whether they ever shrink.
174
+ options:
175
+ - Never: bounds only grow, so the view never jumps under the reader.
176
+ - On drop: bounds fit the content again after each edit.
177
+ ```
178
+
179
+ ```mdl
180
+ decision D-6: Never.
181
+ date: 2026-10-07
182
+ by: user:alice
183
+ answers: Q-1
184
+ ```
package/lang/core.mdl ADDED
@@ -0,0 +1,203 @@
1
+ ---
2
+ id: org.dxos.spec.core
3
+ name: DSL.Core
4
+ version: 1.0
5
+ ---
6
+
7
+ The minimal base language. Defines document format and the `ext` primitive only.
8
+ All domain constructs — type, op, feat, scenario, test, ui, db, service, etc. — are extensions.
9
+
10
+ ## Document Format
11
+
12
+ A `.mdl` file has three parts:
13
+
14
+ 1. **Frontmatter** — YAML block delimited by `---`. Contains document metadata.
15
+ 2. **Body** — Standard Markdown prose, headings, and lists.
16
+ 3. **Blocks** — Typed fenced sections carrying structured declarations.
17
+
18
+ ### Frontmatter
19
+
20
+ ```
21
+ id: URI # globally unique document identifier
22
+ name: Identifier # human-readable name
23
+ version: SemVer # document version
24
+ extends?: URI[] # specs this document extends (transitive)
25
+ ```
26
+
27
+ ### Blocks
28
+
29
+ All blocks use the `mdl` fence. The first line of the body declares the block
30
+ type, optional identifier, and optional title:
31
+
32
+ ````
33
+ ```mdl
34
+ <type> [<id>][: <title>]
35
+ key: value
36
+ key?: TypeExpr
37
+ key: a | b | c
38
+ ```
39
+ ````
40
+
41
+ - `<type>` must be declared in the Extensions section of this document or an ancestor.
42
+ - `<id>` is an optional locally-scoped identifier (e.g. `F-1.1`, `Board`).
43
+ - `<title>` is optional human-readable prose after the colon.
44
+ - Block identifiers must be unique within the document.
45
+
46
+ ### Block Body Syntax
47
+
48
+ Within a block, the body is a sequence of key-value pairs:
49
+
50
+ ```
51
+ key: value # scalar
52
+ key: a | b | c # union list (literals)
53
+ key?: TypeExpr # optional field declaration
54
+ key: # multi-line value
55
+ - item one
56
+ - item two
57
+ # comment
58
+ ```
59
+
60
+ When an extension declares `inline-prose: true`, prose may appear between
61
+ the header line and the first key-value pair:
62
+
63
+ ````
64
+ ```mdl
65
+ feat F-1: Start Game
66
+ A new Board is created with pieces in starting positions. ← inline prose
67
+ req F-1.1: White moves first.
68
+ ```
69
+ ````
70
+
71
+ ### Cross-References
72
+
73
+ Any declared block identifier may be referenced elsewhere in the document as `[<id>]`.
74
+ The linter verifies that all references resolve to a declared block.
75
+
76
+ ### External References
77
+
78
+ A spec names a block of another spec as `<spec id>#<item>`, where the item is a block id or `req` id
79
+ (`com.acme.canvas#F-3.1`), and declares that spec under `## Dependencies` (below). A
80
+ block may name code, or anything else outside the specs, by **source key**:
81
+ `github:<owner>/<repo>/<path>[#<fragment>]`, with the path relative to the repository root.
82
+
83
+ | Key names | Example | Fragment |
84
+ | ------------------- | -------------------------------------------------------------- | ------------------- |
85
+ | A code symbol | `github:dxos/dxos/packages/sdk/types/src/types/Spec.ts#make` | Symbol (`A.b` ok) |
86
+ | A whole file | `github:dxos/dxos/packages/apps/composer-app/vite.config.ts` | none |
87
+
88
+ A spec does not name the code that implements it: those links are annotations kept outside the
89
+ spec (a review's `evidence:`, see `review.mdl`), and the spec viewer renders them as decorations
90
+ beside the items they annotate. Tools resolve keys against a local checkout of the repository. A
91
+ key is a location, not a version: it names whatever the checkout holds.
92
+
93
+ ---
94
+
95
+ ## Extensions Section
96
+
97
+ Every document that uses non-core block types MUST declare them:
98
+
99
+ ```
100
+ ## Extensions
101
+
102
+ | Term | URI |
103
+ |----------|----------------------------|
104
+ | `type` | dxos.spec/ext/type@1.0 |
105
+ | `feat` | dxos.spec/ext/feat@1.0 |
106
+ ```
107
+
108
+ An extension definition is either:
109
+ - **External** — resolved by URI (registry lookup, future tooling).
110
+ - **Inline** — defined in the document's Appendix using `ext` blocks.
111
+
112
+ A document may use both: external URIs for standard extensions,
113
+ inline `ext` blocks for custom or experimental ones.
114
+
115
+ ---
116
+
117
+ ## Dependencies Section
118
+
119
+ A spec lists the other specs it builds on under `## Dependencies`, after the opening prose and
120
+ before `## Extensions`, one `uses` block per spec. A Composer plugin's runtime dependencies are the
121
+ exception: they go in its `plugin` block's `dependsOn` (plugin dialect) and are never repeated under
122
+ `uses`. The identifier is the depended-on spec's `id`;
123
+ the inline prose is required and says what this spec takes from it.
124
+
125
+ ```mdl
126
+ ext uses
127
+ uri: dxos.spec.core/uses
128
+ desc: Declares that this spec builds on another spec, identified by its frontmatter id.
129
+ inline-prose: true
130
+ fields:
131
+ id: URI # the depended-on spec's id (the block identifier)
132
+ syntax: |
133
+ uses org.dxos.ui.react-ui-canvas: The engine whose types and operations this canvas models.
134
+ ```
135
+
136
+ A reference into another spec is `<spec id>#<item>`, where the item is any block id or `req` id.
137
+
138
+ ---
139
+
140
+ ## The `ext` Primitive
141
+
142
+ `ext` is the only block type the core language natively provides.
143
+ It is self-describing — defined here using itself:
144
+
145
+ ```mdl
146
+ ext ext
147
+ uri: dxos.spec.core/ext
148
+ desc: Declares a new block type or extends an existing one.
149
+ fields:
150
+ uri: URI # canonical identifier for this extension (required)
151
+ desc: Prose # human description (required)
152
+ extends?: ExtRef # parent extension — inherits all parent fields
153
+ fields?: FieldMap # fields valid on instances of this block type
154
+ adds-fields?: FieldMap # additional fields merged into parent (use with extends)
155
+ nesting?: self | none # whether instances may contain same-type blocks
156
+ inline-prose?: Boolean # first non-key line treated as prose value
157
+ syntax?: CodeBlock # reference syntax (non-normative)
158
+ example?: CodeBlock # usage example (non-normative)
159
+ ```
160
+
161
+ ---
162
+
163
+ ## Primitive Types
164
+
165
+ The following types are available in `ext` field declarations.
166
+ They are the vocabulary of the meta-language.
167
+
168
+ | Type | Description |
169
+ |--------------|--------------------------------------------------------------|
170
+ | `Prose` | Free-form text, single or multi-line |
171
+ | `Identifier` | Alphanumeric name, hyphens allowed — e.g. `Board`, `F-1` |
172
+ | `URI` | Dot-path or URL identifier — e.g. `dxos.spec/ext/type@1.0` |
173
+ | `SemVer` | Semantic version string — e.g. `1.0.0` |
174
+ | `Boolean` | `true` or `false` |
175
+ | `TypeExpr` | Type reference or inline type — e.g. `Color`, `Piece?` |
176
+ | `FieldMap` | Named fields: `name[?]: TypeExpr # comment` |
177
+ | `UnionList` | Pipe-separated literals: `a \| b \| c` |
178
+ | `ProseList` | Bulleted list of prose items |
179
+ | `CodeBlock` | Literal indented or fenced text |
180
+ | `ExtRef` | Reference to a declared extension name |
181
+ | `TagList` | Space or comma-separated tag identifiers |
182
+
183
+ ---
184
+
185
+ ## Resolution Rules
186
+
187
+ 1. When a block type appears in a document body, the linter looks it up
188
+ in the nearest enclosing Extensions table (this document or any ancestor).
189
+ 2. If the URI resolves to an inline `ext` block in an Appendix, that definition is used.
190
+ 3. If the URI is external, the linter fetches the definition from a registry.
191
+ 4. An unresolvable block type is a lint error.
192
+ 5. Field names not declared in the `ext` definition are lint warnings.
193
+
194
+ ---
195
+
196
+ ## Non-Goals
197
+
198
+ The core language deliberately omits:
199
+
200
+ - Execution semantics — `.mdl` is a specification, not a program.
201
+ - Type checking — field values are not verified against TypeExpr at the core level.
202
+ - Ordering constraints — sections may appear in any order.
203
+ - Verification — requirements are semi-formal; the language is not a proof system.
@@ -0,0 +1,149 @@
1
+ ---
2
+ id: org.dxos.plugin.chess
3
+ name: ChessPlugin
4
+ version: 0.1.0
5
+ ---
6
+
7
+ A two-player chess game plugin for `DXOS` Composer.
8
+
9
+ ## Extensions
10
+
11
+ The following extension dialects are used in this document.
12
+ Each extension is defined in the Appendix or resolved via its URI.
13
+
14
+ | Term | URI |
15
+ |--------|-----------------------------|
16
+ | `type` | `org.dxos.mdl.type@1.0` |
17
+ | `feat` | `org.dxos.mdl.feat@1.0` |
18
+ | `scenario` | `org.dxos.mdl.scenario@1.0` |
19
+
20
+ ## Types
21
+
22
+ ```mdl
23
+ type Color
24
+ literals: white | black
25
+ ```
26
+
27
+ ```mdl
28
+ type PieceKind
29
+ literals: pawn | rook | knight | bishop | queen | king
30
+ ```
31
+
32
+ ```mdl
33
+ type Piece
34
+ fields:
35
+ kind: PieceKind
36
+ color: Color
37
+ ```
38
+
39
+ ```mdl
40
+ type Square
41
+ fields:
42
+ file: a | b | c | d | e | f | g | h
43
+ rank: 1..8
44
+ piece?: Piece
45
+ ```
46
+
47
+ ```mdl
48
+ type Move
49
+ fields:
50
+ from: Square
51
+ to: Square
52
+ promotion?: PieceKind # only valid for pawn reaching back rank
53
+ ```
54
+
55
+ ```mdl
56
+ type Board
57
+ fields:
58
+ squares: Square[8][8]
59
+ turn: Color
60
+ status: playing | check | checkmate | stalemate
61
+ moves: Move[] # full move history
62
+ ```
63
+
64
+ ## Features
65
+
66
+ ```mdl
67
+ feat F-1: Start Game
68
+
69
+ req F-1.1: New Board created with pieces in standard starting positions.
70
+ req F-1.2: White moves first.
71
+ ```
72
+
73
+ ```mdl
74
+ feat F-2: Make Move
75
+
76
+ req F-2.1:
77
+ when: player submits a Move on their turn
78
+ then: Move validated against chess rules
79
+ errors: [InvalidMove, WrongTurn, GameOver]
80
+
81
+ req F-2.2:
82
+ when: Move is valid
83
+ then: Board updated; turn advances to opponent
84
+
85
+ req F-2.3:
86
+ when: resulting position leaves opponent's king in check
87
+ then: Board.status set to check
88
+
89
+ req F-2.4:
90
+ when: no legal moves remain for the side to move
91
+ then: Board.status set to checkmate (if in check) or stalemate
92
+ ```
93
+
94
+ ## Acceptance
95
+
96
+ ```mdl
97
+ scenario T-1: New game starting position
98
+ given: a new game is started
99
+ then:
100
+ - Board.turn === white
101
+ - Board.status === playing
102
+ - each player has 16 pieces in standard positions
103
+ ```
104
+
105
+ ```mdl
106
+ scenario T-2: Illegal move rejected
107
+ given: it is white's turn
108
+ when: white attempts to move a black piece
109
+ then: WrongTurn error; Board unchanged
110
+ ```
111
+
112
+ ---
113
+
114
+ ## Appendix: Extension Definitions
115
+
116
+ Extension block types used in this document are defined below using
117
+ the core `ext` primitive — the only construct the base language provides.
118
+
119
+ ```mdl
120
+ ext type
121
+ uri: org.dxos.mdl.type@1.0
122
+ desc: A named data structure with typed fields and optional literals.
123
+ fields:
124
+ desc?: Prose
125
+ fields?: FieldMap # name[?]: TypeExpr (# inline comment)
126
+ literals?: UnionList # a | b | c
127
+ extends?: TypeRef[]
128
+ ```
129
+
130
+ ```mdl
131
+ ext feat
132
+ uri: org.dxos.mdl.feat@1.0
133
+ desc: A named feature grouping one or more requirements.
134
+ fields:
135
+ desc?: Prose
136
+ req: RequirementList
137
+ nesting: self # feat blocks may contain feat blocks
138
+ ```
139
+
140
+ ```mdl
141
+ ext scenario
142
+ uri: org.dxos.mdl.scenario@1.0
143
+ desc: An acceptance scenario expressed as given / when / then steps.
144
+ fields:
145
+ given?: Step | Step[]
146
+ when?: Step | Step[]
147
+ then: Step | Step[]
148
+ tags?: TagList
149
+ ```