@adhd/dispatch-base-spec

TypeScript types, JSON Schema documents, cross-language structural validators, and operation vocabulary for the dispatch plan ecosystem.

npm install @adhd/dispatch-base-spec

Design tenets

1. Shape ops are the specification

The shape.ops[] array on every operation is simultaneously a prompt for generative agents, a verification contract for gitnexus post-execution AST checks, and a machine-execution spec for future AST-based tool-call executors. Every add-field, add-param, and set-key carries an exact type in to — never null. An automated transformer can produce correct output from shape ops alone, with no LLM required (D-05).

2. Cost optimization is structural, not heuristic

Every dispatch costs a fixed base overhead (B), reads source files (Sᵢ), and produces output tokens (Kᵢ). The optimizer computes the minimum total token cost across all three components, respecting DAG precedence and context-window quality cliffs. This is an NP-hard problem that admits polynomial special cases. The optimizer's batch assignment pays back the planning cost on its first execution wave (SCOPE.md §A1–A4).

3. Agents never read dag.json raw

This package defines the data contract that every consumer — human CLI, MCP server, orchestrator, Python validator — agrees on. Agents interact with dag.json through typed tools (dag.milestone_add, dag.pending_clear) that enforce structural validity, referential integrity, and per-kind operation constraints. No agent context window ever contains raw dag.json text (D-02).

4. Operational fidelity

Every milestone carries a guard — a pinned shell command that proves completion. Every operation carries a shape — a structural spec that describes exactly what changes, with what types, at what location. A plan that passes its guards with its shapes verified by gitnexus is a plan that actually worked, not a plan that an agent thinks worked (D-05, D-12).

5. Cross-language by design

TypeScript types are the canonical representation, but this package ships JSON Schema (dag-v5.schema.json) and a per-kind operation vocabulary mapping (valid-ops-by-kind.json) as plain JSON data. A Python orchestrator can validate a dag.json with jsonschema and constrain tool inputs with op in mapping[kind]. No npm install needed.

6. Plans are reusable, execution is amortized

A plan is authored once. Its shape ops, guards, and dependencies are committed to git. The orchestrator replays it as many times as needed — across different repos, different model tiers, different provider backends. The one-time planning token cost is amortized over every execution. The optimizer's savings compound.

Exports

| Export | Purpose | | --------------------- | ----------------------------------------------------------------------------------------------------- | | types | DagJson, DagSnapshot, DispatchUnit, OperationDag, Shape, MilestoneSnapshot, all sub-types | | validateDagJson | Structural + cycle + ref integrity + op/kind constraint validation | | validateSnapshot | D-07 eligibility invariant + status/wave/ref validation | | assertValidDagJson | Throwing variant — narrows type to DagJson | | assertValidSnapshot | Throwing variant — narrows to DagSnapshot | | upgradeDagToCurrent | (dag) → void — bring any older dag.json up to schema v5 in place (run by every read path); v5 providers entries are camelCase PartialBindings from @adhd/agent-base-types | | migrateDag | (from, to, dag) → void — sequential v2→v3→v4→v5 schema upgrades | | VALID_OPS_BY_KIND | Record<string, ReadonlySet<ShapeOpType>> | | isValidOpForKind | (kind, op) → boolean — runtime check | | WRITE_CLASS_ACTIONS | ReadonlySet<OperationAction> | | IOptimizerDeps | Interface for optimizer dependency injection |

JSON files shipped in dist

| File | Purpose | | ------------------------ | ------------------------------------------------------- | | dag-v5.schema.json | Full JSON Schema for dag.json — 18 top-level properties | | valid-ops-by-kind.json | 13 kind entries mapping shape.kind → allowed ops |

Lanes and tool grants

A milestone may declare the lane of work it performs and the tool_grant its executing agent holds. validateDagJson refuses a milestone whose grant cannot satisfy its lane, with a typed error (ValidationError.code):

| code | meaning | | --- | --- | | lane_tool_grant_unsatisfied | the grant lacks every alternative of at least one requirement group of the lane | | lane_tool_grant_missing | a lane is declared with no tool_grant, so the grant cannot be proven | | unknown_lane | the lane is not in LANE_TOOL_REQUIREMENTS (file-ops, research, execution, backlog) | | invalid_tool_grant / invalid_lane | wrong type |

LANE_TOOL_REQUIREMENTS, unsatisfiedLaneGroups and grantCovers are exported (a trailing * in a grant or a requirement is a prefix wildcard, e.g. mcp__backlog__*). A milestone with no lane is unaffected.

Zero dependencies

This package imports nothing but TypeScript. No filesystem, no node APIs, no third-party libs. platform:shared — safe in browser, server, and CLI contexts.