@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.
- package/LICENSE +105 -0
- package/README.md +24 -2
- package/bin/deus.ts +42 -0
- package/dist/lib/chunk-blocks.mjs +151 -0
- package/dist/lib/chunk-blocks.mjs.map +1 -0
- package/dist/lib/chunk-check.mjs +452 -0
- package/dist/lib/chunk-check.mjs.map +1 -0
- package/dist/lib/chunk-completion.mjs +112 -0
- package/dist/lib/chunk-completion.mjs.map +1 -0
- package/dist/lib/chunk-extension.mjs +396 -0
- package/dist/lib/chunk-extension.mjs.map +1 -0
- package/dist/lib/chunk-parse.mjs +21 -0
- package/dist/lib/chunk-parse.mjs.map +1 -0
- package/dist/lib/cli.mjs +946 -0
- package/dist/lib/cli.mjs.map +1 -0
- package/dist/lib/extension.mjs +4 -0
- package/dist/lib/index.mjs +6 -0
- package/dist/lib/parse.mjs +4 -0
- package/dist/lib/review.mjs +260 -0
- package/dist/lib/review.mjs.map +1 -0
- package/dist/lib/spec-index.mjs +28 -0
- package/dist/lib/spec-index.mjs.map +1 -0
- package/dist/types/bin/deus.d.ts +3 -0
- package/dist/types/bin/deus.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts +7 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts +8 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts +5 -0
- package/dist/types/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.d.ts.map +1 -0
- package/dist/types/src/cli/changelog.d.ts +25 -0
- package/dist/types/src/cli/changelog.d.ts.map +1 -0
- package/dist/types/src/cli/cli.test.d.ts +2 -0
- package/dist/types/src/cli/cli.test.d.ts.map +1 -0
- package/dist/types/src/cli/errors.d.ts +183 -0
- package/dist/types/src/cli/errors.d.ts.map +1 -0
- package/dist/types/src/cli/features.d.ts +58 -0
- package/dist/types/src/cli/features.d.ts.map +1 -0
- package/dist/types/src/cli/git.d.ts +8 -0
- package/dist/types/src/cli/git.d.ts.map +1 -0
- package/dist/types/src/cli/index.d.ts +12 -0
- package/dist/types/src/cli/index.d.ts.map +1 -0
- package/dist/types/src/cli/lint.d.ts +17 -0
- package/dist/types/src/cli/lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa-lint.d.ts +40 -0
- package/dist/types/src/cli/qa-lint.d.ts.map +1 -0
- package/dist/types/src/cli/qa.d.ts +86 -0
- package/dist/types/src/cli/qa.d.ts.map +1 -0
- package/dist/types/src/cli/review.d.ts +38 -0
- package/dist/types/src/cli/review.d.ts.map +1 -0
- package/dist/types/src/cli/spec-index.d.ts +17 -0
- package/dist/types/src/cli/spec-index.d.ts.map +1 -0
- package/dist/types/src/extension/blocks.d.ts +65 -0
- package/dist/types/src/extension/blocks.d.ts.map +1 -0
- package/dist/types/src/extension/check.d.ts +99 -0
- package/dist/types/src/extension/check.d.ts.map +1 -0
- package/dist/types/src/extension/check.test.d.ts +2 -0
- package/dist/types/src/extension/check.test.d.ts.map +1 -0
- package/dist/types/src/extension/code.d.ts +7 -0
- package/dist/types/src/extension/code.d.ts.map +1 -0
- package/dist/types/src/extension/complete.d.ts +6 -0
- package/dist/types/src/extension/complete.d.ts.map +1 -0
- package/dist/types/src/extension/completion.d.ts +10 -0
- package/dist/types/src/extension/completion.d.ts.map +1 -0
- package/dist/types/src/extension/constants.d.ts +6 -0
- package/dist/types/src/extension/constants.d.ts.map +1 -0
- package/dist/types/src/extension/fences.d.ts +10 -0
- package/dist/types/src/extension/fences.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.d.ts +3 -0
- package/dist/types/src/extension/gen/mdl.d.ts.map +1 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts +2 -0
- package/dist/types/src/extension/gen/mdl.terms.d.ts.map +1 -0
- package/dist/types/src/extension/index.d.ts +8 -0
- package/dist/types/src/extension/index.d.ts.map +1 -0
- package/dist/types/src/extension/language.d.ts +20 -0
- package/dist/types/src/extension/language.d.ts.map +1 -0
- package/dist/types/src/extension/lint.d.ts +8 -0
- package/dist/types/src/extension/lint.d.ts.map +1 -0
- package/dist/types/src/extension/parse.d.ts +6 -0
- package/dist/types/src/extension/parse.d.ts.map +1 -0
- package/dist/types/src/extension/parser.test.d.ts +2 -0
- package/dist/types/src/extension/parser.test.d.ts.map +1 -0
- package/dist/types/src/extension/refs.d.ts +32 -0
- package/dist/types/src/extension/refs.d.ts.map +1 -0
- package/dist/types/src/extension/refs.test.d.ts +2 -0
- package/dist/types/src/extension/refs.test.d.ts.map +1 -0
- package/dist/types/src/extension/syntax.d.ts +12 -0
- package/dist/types/src/extension/syntax.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +3 -0
- package/dist/types/src/index.d.ts.map +1 -0
- package/dist/types/src/review/fields.d.ts +9 -0
- package/dist/types/src/review/fields.d.ts.map +1 -0
- package/dist/types/src/review/index.d.ts +5 -0
- package/dist/types/src/review/index.d.ts.map +1 -0
- package/dist/types/src/review/review.d.ts +70 -0
- package/dist/types/src/review/review.d.ts.map +1 -0
- package/dist/types/src/review/review.test.d.ts +2 -0
- package/dist/types/src/review/review.test.d.ts.map +1 -0
- package/dist/types/src/review/source-key.d.ts +35 -0
- package/dist/types/src/review/source-key.d.ts.map +1 -0
- package/dist/types/src/review/symbol.d.ts +17 -0
- package/dist/types/src/review/symbol.d.ts.map +1 -0
- package/dist/types/src/review/symbol.test.d.ts +2 -0
- package/dist/types/src/review/symbol.test.d.ts.map +1 -0
- package/dist/types/src/spec-index/index.d.ts +3 -0
- package/dist/types/src/spec-index/index.d.ts.map +1 -0
- package/dist/types/src/spec-index/parse.d.ts +11 -0
- package/dist/types/src/spec-index/parse.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.d.ts +21 -0
- package/dist/types/src/spec-index/spec-index.d.ts.map +1 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts +2 -0
- package/dist/types/src/spec-index/spec-index.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -0
- package/docs/DESIGN.md +561 -0
- package/docs/IDIOMS.md +265 -0
- package/lang/PLUGIN-.template.mdl +115 -0
- package/lang/app.mdl +200 -0
- package/lang/changelog.mdl +184 -0
- package/lang/core.mdl +203 -0
- package/lang/examples/chess-1.mdl +149 -0
- package/lang/examples/chess-2.mdl +203 -0
- package/lang/examples/chess-3.mdl +231 -0
- package/lang/features.mdl +92 -0
- package/lang/plugin.mdl +59 -0
- package/lang/qa.mdl +383 -0
- package/lang/review.mdl +103 -0
- package/lang/sql.mdl +72 -0
- package/package.json +74 -3
- package/src/cli/__fixtures__/bad-decision.mdl +13 -0
- package/src/cli/__fixtures__/features/CYCLE.mdl +25 -0
- package/src/cli/__fixtures__/features/FEATURES.mdl +47 -0
- package/src/cli/__fixtures__/features/SPEC.mdl +22 -0
- package/src/cli/__fixtures__/features/SPEC.review.mdl +32 -0
- package/src/cli/__fixtures__/features/TASKS.md +5 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.mdl +7 -0
- package/src/cli/__fixtures__/lint-refs/SPEC.review.mdl +7 -0
- package/src/cli/__fixtures__/qa-lint/packages/plugins/plugin-risky/PLUGIN.mdl +29 -0
- package/src/cli/__fixtures__/qa-list/plugin-sample/spec/PLUGIN.mdl +51 -0
- package/src/cli/__fixtures__/review/SPEC.mdl +23 -0
- package/src/cli/__fixtures__/review/SPEC.review.mdl +26 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/PLUGIN.review.mdl +14 -0
- package/src/cli/__fixtures__/review/plugin-deps-diverged/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-empty/dx.config.ts +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-mismatch/dx.config.ts +10 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.mdl +9 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/PLUGIN.review.mdl +13 -0
- package/src/cli/__fixtures__/review/plugin-deps-noplugin/dx.config.ts +7 -0
- package/src/cli/changelog.ts +122 -0
- package/src/cli/cli.test.ts +359 -0
- package/src/cli/errors.ts +23 -0
- package/src/cli/features.ts +320 -0
- package/src/cli/git.ts +35 -0
- package/src/cli/index.ts +27 -0
- package/src/cli/lint.ts +75 -0
- package/src/cli/qa-lint.ts +206 -0
- package/src/cli/qa.ts +300 -0
- package/src/cli/review.ts +359 -0
- package/src/cli/spec-index.ts +54 -0
- package/src/extension/blocks.ts +169 -0
- package/src/extension/check.test.ts +629 -0
- package/src/extension/check.ts +552 -0
- package/src/extension/code.ts +99 -0
- package/src/extension/complete.ts +34 -0
- package/src/extension/completion.ts +64 -0
- package/src/extension/constants.ts +28 -0
- package/src/extension/fences.ts +270 -0
- package/src/extension/gen/mdl.terms.ts +16 -0
- package/src/extension/gen/mdl.ts +16 -0
- package/src/extension/index.ts +25 -0
- package/src/extension/language.ts +33 -0
- package/src/extension/lint.ts +19 -0
- package/src/extension/mdl.grammar +60 -0
- package/src/extension/parse.ts +31 -0
- package/src/extension/parser.test.ts +248 -0
- package/src/extension/refs.test.ts +95 -0
- package/src/extension/refs.ts +94 -0
- package/src/extension/syntax.ts +25 -0
- package/src/index.ts +6 -0
- package/src/review/fields.ts +31 -0
- package/src/review/index.ts +8 -0
- package/src/review/review.test.ts +111 -0
- package/src/review/review.ts +184 -0
- package/src/review/source-key.ts +63 -0
- package/src/review/symbol.test.ts +47 -0
- package/src/review/symbol.ts +96 -0
- package/src/spec-index/index.ts +6 -0
- package/src/spec-index/parse.ts +22 -0
- package/src/spec-index/spec-index.test.ts +56 -0
- 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.
|