@adhd/dispatch-base-spec 0.0.1 โ†’ 0.0.3

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/CHANGELOG.md ADDED
@@ -0,0 +1,41 @@
1
+ ## 0.0.3 (2026-07-23)
2
+
3
+
4
+ ### ๐Ÿš€ Features
5
+
6
+ - session batch โ€” dispatch tool-exec + provider routing, publish hygiene, agent/env/apigen fixes
7
+
8
+ - **release:** nx release independent versioning + verify-dist-load publish gate (Agent 2)
9
+
10
+
11
+ ### ๐Ÿฉน Fixes
12
+
13
+ - **lint:** eliminate @typescript-eslint/no-explicit-any across 5 packages (LINT-ANY-001)
14
+
15
+ - **dispatch:** repair paths dangled by the superseded-plan relocation
16
+
17
+
18
+ ### โค๏ธ Thank You
19
+
20
+ - pseudosky
21
+
22
+ ## 0.0.2 (2026-07-23)
23
+
24
+
25
+ ### ๐Ÿš€ Features
26
+
27
+ - session batch โ€” dispatch tool-exec + provider routing, publish hygiene, agent/env/apigen fixes
28
+
29
+ - **release:** nx release independent versioning + verify-dist-load publish gate (Agent 2)
30
+
31
+
32
+ ### ๐Ÿฉน Fixes
33
+
34
+ - **lint:** eliminate @typescript-eslint/no-explicit-any across 5 packages (LINT-ANY-001)
35
+
36
+ - **dispatch:** repair paths dangled by the superseded-plan relocation
37
+
38
+
39
+ ### โค๏ธ Thank You
40
+
41
+ - pseudosky
package/README.md ADDED
@@ -0,0 +1,90 @@
1
+ # @adhd/dispatch-base-spec
2
+
3
+ TypeScript types, JSON Schema documents, cross-language structural validators,
4
+ and operation vocabulary for the dispatch plan ecosystem.
5
+
6
+ ```bash
7
+ npm install @adhd/dispatch-base-spec
8
+ ```
9
+
10
+ ---
11
+
12
+ ## Design tenets
13
+
14
+ ### 1. Shape ops are the specification
15
+
16
+ The `shape.ops[]` array on every operation is simultaneously a **prompt** for
17
+ generative agents, a **verification contract** for gitnexus post-execution AST
18
+ checks, and a **machine-execution spec** for future AST-based tool-call
19
+ executors. Every `add-field`, `add-param`, and `set-key` carries an exact type
20
+ in `to` โ€” never `null`. An automated transformer can produce correct output
21
+ from shape ops alone, with no LLM required (D-05).
22
+
23
+ ### 2. Cost optimization is structural, not heuristic
24
+
25
+ Every dispatch costs a fixed base overhead (B), reads source files (Sแตข), and
26
+ produces output tokens (Kแตข). The optimizer computes the **minimum total token
27
+ cost** across all three components, respecting DAG precedence and context-window
28
+ quality cliffs. This is an NP-hard problem that admits polynomial special
29
+ cases. The optimizer's batch assignment pays back the planning cost on its first
30
+ execution wave (SCOPE.md ยงA1โ€“A4).
31
+
32
+ ### 3. Agents never read dag.json raw
33
+
34
+ This package defines the data contract that every consumer โ€” human CLI, MCP
35
+ server, orchestrator, Python validator โ€” agrees on. Agents interact with
36
+ dag.json through typed tools (`dag.milestone_add`, `dag.pending_clear`) that
37
+ enforce structural validity, referential integrity, and per-kind operation
38
+ constraints. No agent context window ever contains raw dag.json text (D-02).
39
+
40
+ ### 4. Operational fidelity
41
+
42
+ Every milestone carries a **guard** โ€” a pinned shell command that proves
43
+ completion. Every operation carries a **shape** โ€” a structural spec that
44
+ describes exactly what changes, with what types, at what location. A plan that
45
+ passes its guards with its shapes verified by gitnexus is a plan that actually
46
+ worked, not a plan that an agent _thinks_ worked (D-05, D-12).
47
+
48
+ ### 5. Cross-language by design
49
+
50
+ TypeScript types are the canonical representation, but this package ships
51
+ **JSON Schema** (`dag-v4.schema.json`) and a **per-kind operation vocabulary
52
+ mapping** (`valid-ops-by-kind.json`) as plain JSON data. A Python orchestrator
53
+ can validate a dag.json with `jsonschema` and constrain tool inputs with
54
+ `op in mapping[kind]`. No npm install needed.
55
+
56
+ ### 6. Plans are reusable, execution is amortized
57
+
58
+ A plan is authored once. Its shape ops, guards, and dependencies are committed
59
+ to git. The orchestrator replays it as many times as needed โ€” across different
60
+ repos, different model tiers, different provider backends. The one-time planning
61
+ token cost is amortized over every execution. The optimizer's savings compound.
62
+
63
+ ---
64
+
65
+ ## Exports
66
+
67
+ | Export | Purpose |
68
+ | --------------------- | ----------------------------------------------------------------------------------------------------- |
69
+ | `types` | `DagJson`, `DagSnapshot`, `DispatchUnit`, `OperationDag`, `Shape`, `MilestoneSnapshot`, all sub-types |
70
+ | `validateDagJson` | Structural + cycle + ref integrity + op/kind constraint validation |
71
+ | `validateSnapshot` | D-07 eligibility invariant + status/wave/ref validation |
72
+ | `assertValidDagJson` | Throwing variant โ€” narrows type to `DagJson` |
73
+ | `assertValidSnapshot` | Throwing variant โ€” narrows to `DagSnapshot` |
74
+ | `migrateDag` | `(from, to, dag) โ†’ void` โ€” sequential v2โ†’v3โ†’v4 schema upgrades |
75
+ | `VALID_OPS_BY_KIND` | `Record<string, ReadonlySet<ShapeOpType>>` |
76
+ | `isValidOpForKind` | `(kind, op) โ†’ boolean` โ€” runtime check |
77
+ | `WRITE_CLASS_ACTIONS` | `ReadonlySet<OperationAction>` |
78
+ | `IOptimizerDeps` | Interface for optimizer dependency injection |
79
+
80
+ ### JSON files shipped in dist
81
+
82
+ | File | Purpose |
83
+ | ------------------------ | ------------------------------------------------------- |
84
+ | `dag-v4.schema.json` | Full JSON Schema for dag.json โ€” 18 top-level properties |
85
+ | `valid-ops-by-kind.json` | 13 kind entries mapping `shape.kind` โ†’ allowed ops |
86
+
87
+ ## Zero dependencies
88
+
89
+ This package imports nothing but TypeScript. No filesystem, no node APIs, no
90
+ third-party libs. `platform:shared` โ€” safe in browser, server, and CLI contexts.
@@ -0,0 +1,294 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://adhd.dev/schemas/dag-v4.schema.json",
4
+ "title": "DagJson v4",
5
+ "description": "Authored plan document โ€” intent + execution log. Schema version 4.",
6
+ "type": "object",
7
+ "required": [
8
+ "schema_version",
9
+ "plan_kind",
10
+ "description",
11
+ "problem",
12
+ "approach",
13
+ "executor",
14
+ "phases",
15
+ "terminal",
16
+ "optimization",
17
+ "providers",
18
+ "effort_max_tokens",
19
+ "milestones",
20
+ "operations",
21
+ "dispatch_log"
22
+ ],
23
+ "properties": {
24
+ "schema_version": { "const": 4 },
25
+ "plan_kind": { "enum": ["brownfield", "greenfield"] },
26
+ "description": { "type": "string", "minLength": 1 },
27
+ "problem": { "type": "string" },
28
+ "approach": { "type": "string" },
29
+ "executor": { "type": "string" },
30
+ "executor_model": { "enum": ["Haiku", "Sonnet", "Opus"] },
31
+ "executor_effort": { "enum": ["low", "medium", "high", "xhigh", "max"] },
32
+ "phases": {
33
+ "type": "array",
34
+ "minItems": 1,
35
+ "items": { "type": "string" }
36
+ },
37
+ "terminal": {
38
+ "oneOf": [
39
+ { "type": "string" },
40
+ { "type": "array", "items": { "type": "string" } }
41
+ ]
42
+ },
43
+ "assumed_baseline": {
44
+ "oneOf": [
45
+ { "type": "array", "items": { "type": "string" } },
46
+ { "type": "object" }
47
+ ]
48
+ },
49
+ "optimization": {
50
+ "type": "object",
51
+ "required": ["sentinel_fanout", "b_per_tier", "context_window_per_tier"],
52
+ "properties": {
53
+ "sentinel_fanout": {
54
+ "type": "object",
55
+ "required": [
56
+ "enabled",
57
+ "write_multiplier",
58
+ "read_multiplier",
59
+ "hit_probability"
60
+ ],
61
+ "properties": {
62
+ "enabled": { "type": "boolean" },
63
+ "write_multiplier": { "type": "number" },
64
+ "read_multiplier": { "type": "number" },
65
+ "hit_probability": { "type": "number" }
66
+ }
67
+ },
68
+ "b_per_tier": { "type": "object" },
69
+ "context_window_per_tier": { "type": "object" },
70
+ "context_window_override": {
71
+ "oneOf": [{ "type": "object" }, { "type": "null" }]
72
+ },
73
+ "b_override": { "oneOf": [{ "type": "object" }, { "type": "null" }] }
74
+ }
75
+ },
76
+ "providers": { "type": "object" },
77
+ "effort_max_tokens": { "type": "object" },
78
+ "milestones": {
79
+ "type": "object",
80
+ "minProperties": 1,
81
+ "additionalProperties": {
82
+ "type": "object",
83
+ "required": ["description", "authored_by", "phase", "depends_on"],
84
+ "properties": {
85
+ "description": { "type": "string" },
86
+ "rationale": { "type": "string" },
87
+ "authored_by": { "type": "string" },
88
+ "pending": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
89
+ "triggered_by": {
90
+ "oneOf": [{ "type": "string" }, { "type": "null" }]
91
+ },
92
+ "phase": { "type": "string" },
93
+ "depends_on": { "type": "array", "items": { "type": "string" } },
94
+ "agent": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
95
+ "model": {
96
+ "oneOf": [
97
+ { "enum": ["Haiku", "Sonnet", "Opus"] },
98
+ { "type": "null" }
99
+ ]
100
+ },
101
+ "effort": {
102
+ "oneOf": [
103
+ { "enum": ["low", "medium", "high", "xhigh", "max"] },
104
+ { "type": "null" }
105
+ ]
106
+ },
107
+ "two_stage": { "type": "boolean" },
108
+ "read_only": { "type": "array", "items": { "type": "string" } },
109
+ "guard": { "oneOf": [{ "type": "string" }, { "type": "null" }] }
110
+ }
111
+ }
112
+ },
113
+ "operations": {
114
+ "oneOf": [
115
+ {
116
+ "type": "array",
117
+ "items": { "$ref": "#/$defs/operation" }
118
+ },
119
+ {
120
+ "type": "object",
121
+ "additionalProperties": { "$ref": "#/$defs/operation" }
122
+ }
123
+ ]
124
+ },
125
+ "dispatch_log": {
126
+ "type": "array",
127
+ "items": { "$ref": "#/$defs/dispatchLogEntry" }
128
+ },
129
+ "cross_plan_deps": {
130
+ "type": "array",
131
+ "items": {
132
+ "type": "object",
133
+ "required": ["plan", "milestone"],
134
+ "properties": {
135
+ "plan": { "type": "string" },
136
+ "milestone": { "type": "string" }
137
+ }
138
+ }
139
+ }
140
+ },
141
+ "$defs": {
142
+ "operation": {
143
+ "type": "object",
144
+ "required": [
145
+ "id",
146
+ "milestone",
147
+ "depends_on",
148
+ "type",
149
+ "action",
150
+ "authored_by",
151
+ "status"
152
+ ],
153
+ "properties": {
154
+ "id": { "type": "string" },
155
+ "milestone": { "type": "string" },
156
+ "depends_on": { "type": "array", "items": { "type": "string" } },
157
+ "type": { "enum": ["automated", "tool-call", "generative"] },
158
+ "action": { "type": "string" },
159
+ "file": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
160
+ "symbol": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
161
+ "provenance": {
162
+ "oneOf": [
163
+ { "enum": ["gitnexus", "manual", "assumed", "vendored"] },
164
+ { "type": "null" }
165
+ ]
166
+ },
167
+ "confidence": {
168
+ "oneOf": [
169
+ { "enum": ["verified", "vendored", "documented", "assumed"] },
170
+ { "type": "null" }
171
+ ]
172
+ },
173
+ "audit_check": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
174
+ "criteria": { "type": "array", "items": { "type": "string" } },
175
+ "tool": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
176
+ "args": { "oneOf": [{ "type": "object" }, { "type": "null" }] },
177
+ "guard": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
178
+ "to_file": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
179
+ "to_symbol": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
180
+ "ki_estimate": { "oneOf": [{ "type": "integer" }, { "type": "null" }] },
181
+ "ki_source": {
182
+ "oneOf": [
183
+ { "enum": ["estimate", "calibrated", "actual"] },
184
+ { "type": "null" }
185
+ ]
186
+ },
187
+ "authored_by": { "type": "string" },
188
+ "status": {
189
+ "enum": ["pending", "in_progress", "complete", "failed", "skipped"]
190
+ },
191
+ "shape": { "$ref": "#/$defs/shape" }
192
+ }
193
+ },
194
+ "shape": {
195
+ "oneOf": [
196
+ {
197
+ "type": "object",
198
+ "required": ["kind"],
199
+ "properties": {
200
+ "kind": {
201
+ "enum": [
202
+ "function",
203
+ "interface",
204
+ "type",
205
+ "class",
206
+ "enum",
207
+ "const",
208
+ "config",
209
+ "env",
210
+ "schema",
211
+ "manifest",
212
+ "script"
213
+ ]
214
+ },
215
+ "ops": {
216
+ "type": "array",
217
+ "items": { "$ref": "#/$defs/shapeOp" }
218
+ }
219
+ }
220
+ },
221
+ {
222
+ "type": "object",
223
+ "required": ["kind", "description", "objective"],
224
+ "properties": {
225
+ "kind": { "const": "doc" },
226
+ "description": { "type": "string" },
227
+ "objective": { "type": "string" },
228
+ "required_sections": {
229
+ "type": "array",
230
+ "items": { "type": "string" }
231
+ }
232
+ }
233
+ },
234
+ {
235
+ "type": "object",
236
+ "required": ["kind", "schema"],
237
+ "properties": {
238
+ "kind": { "const": "structured-output" },
239
+ "schema": { "type": "object" }
240
+ }
241
+ },
242
+ {
243
+ "type": "object",
244
+ "properties": {
245
+ "kind": { "type": "null" }
246
+ }
247
+ }
248
+ ]
249
+ },
250
+ "shapeOp": {
251
+ "type": "object",
252
+ "required": ["op"],
253
+ "properties": {
254
+ "op": { "type": "string" },
255
+ "target": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
256
+ "to": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
257
+ "position": { "oneOf": [{ "type": "integer" }, { "type": "null" }] },
258
+ "required": { "oneOf": [{ "type": "boolean" }, { "type": "null" }] }
259
+ }
260
+ },
261
+ "dispatchLogEntry": {
262
+ "type": "object",
263
+ "required": [
264
+ "id",
265
+ "kind",
266
+ "provider",
267
+ "agent",
268
+ "started_at",
269
+ "operations"
270
+ ],
271
+ "properties": {
272
+ "id": { "type": "string" },
273
+ "kind": { "enum": ["planning", "execution"] },
274
+ "provider": {
275
+ "enum": ["anthropic", "openai", "deepseek", "google", "local"]
276
+ },
277
+ "model": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
278
+ "agent": { "type": "string" },
279
+ "effort": {
280
+ "oneOf": [
281
+ { "enum": ["low", "medium", "high", "xhigh", "max"] },
282
+ { "type": "null" }
283
+ ]
284
+ },
285
+ "started_at": { "type": "string" },
286
+ "completed_at": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
287
+ "operations": { "type": "array", "items": { "type": "string" } },
288
+ "turns": { "type": "array" },
289
+ "results": { "type": "array" },
290
+ "notes": { "type": "array" }
291
+ }
292
+ }
293
+ }
294
+ }
package/package.json CHANGED
@@ -1,11 +1,15 @@
1
1
  {
2
2
  "name": "@adhd/dispatch-base-spec",
3
- "version": "0.0.1",
3
+ "version": "0.0.3",
4
4
  "dependencies": {},
5
5
  "main": "./index.js",
6
6
  "module": "./index.mjs",
7
7
  "typings": "./index.d.ts",
8
8
  "publishConfig": {
9
9
  "access": "public"
10
- }
10
+ },
11
+ "assets": [
12
+ "src/dag-v4.schema.json",
13
+ "src/valid-ops-by-kind.json"
14
+ ]
11
15
  }
@@ -0,0 +1,122 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://adhd.dev/schemas/valid-ops-by-kind.json",
4
+ "title": "Valid Shape Ops by Kind",
5
+ "description": "Mapping from shape.kind to allowed ShapeOpType values. Any consumer (TypeScript validator, Python MCP server, Go AST transformer) can read this file to determine which ops are valid for a given kind without importing TypeScript code.",
6
+ "mapping": {
7
+ "function": [
8
+ "add-param",
9
+ "remove-param",
10
+ "rename-param",
11
+ "retype-param",
12
+ "change-param-optional",
13
+ "reorder-params",
14
+ "change-return"
15
+ ],
16
+ "interface": [
17
+ "add-field",
18
+ "remove-field",
19
+ "rename-field",
20
+ "retype-field",
21
+ "change-field-optional",
22
+ "add-generic",
23
+ "remove-generic",
24
+ "constrain-generic",
25
+ "add-extends",
26
+ "remove-extends"
27
+ ],
28
+ "type": ["add-field", "remove-field", "retype-field"],
29
+ "class": [
30
+ "add-field",
31
+ "remove-field",
32
+ "rename-field",
33
+ "retype-field",
34
+ "change-field-optional",
35
+ "add-param",
36
+ "add-generic",
37
+ "remove-generic",
38
+ "constrain-generic",
39
+ "add-extends",
40
+ "remove-extends"
41
+ ],
42
+ "enum": ["add-field", "remove-field", "rename-field"],
43
+ "const": ["add-var", "remove-var", "rename-var", "change-default"],
44
+ "config": [
45
+ "set-key",
46
+ "remove-key",
47
+ "rename-key",
48
+ "add-entry",
49
+ "remove-entry",
50
+ "update-entry",
51
+ "bump-version",
52
+ "update-checksum"
53
+ ],
54
+ "env": ["set-key", "remove-key", "rename-key"],
55
+ "schema": [
56
+ "add-table",
57
+ "remove-table",
58
+ "add-column",
59
+ "remove-column",
60
+ "rename-column",
61
+ "retype-column",
62
+ "change-nullable",
63
+ "add-index",
64
+ "remove-index"
65
+ ],
66
+ "manifest": ["add-entry", "remove-entry", "bump-version"],
67
+ "doc": [
68
+ "add-section",
69
+ "remove-section",
70
+ "rename-section",
71
+ "update-section"
72
+ ],
73
+ "structured-output": [],
74
+ "script": [
75
+ "add-param",
76
+ "remove-param",
77
+ "rename-param",
78
+ "retype-param",
79
+ "change-param-optional",
80
+ "reorder-params",
81
+ "change-return",
82
+ "add-field",
83
+ "remove-field",
84
+ "rename-field",
85
+ "retype-field",
86
+ "change-field-optional",
87
+ "add-generic",
88
+ "remove-generic",
89
+ "constrain-generic",
90
+ "add-extends",
91
+ "remove-extends",
92
+ "set-key",
93
+ "remove-key",
94
+ "rename-key",
95
+ "add-array-item",
96
+ "remove-array-item",
97
+ "add-var",
98
+ "remove-var",
99
+ "rename-var",
100
+ "change-default",
101
+ "add-section",
102
+ "remove-section",
103
+ "rename-section",
104
+ "update-section",
105
+ "add-table",
106
+ "remove-table",
107
+ "add-column",
108
+ "remove-column",
109
+ "rename-column",
110
+ "retype-column",
111
+ "change-nullable",
112
+ "add-index",
113
+ "remove-index",
114
+ "add-entry",
115
+ "remove-entry",
116
+ "update-entry",
117
+ "bump-version",
118
+ "update-checksum",
119
+ "add-export"
120
+ ]
121
+ }
122
+ }