@adhd/dispatch-base-spec 0.0.1

package/index.d.ts

@@ -0,0 +1,4 @@
+export type { BlastRadiusEntry, CodeKind, Confidence, ConfigKind, CrossPlanDep, DagJson, DagSnapshot, DispatchKind, DispatchLogEntry, DispatchNote, DispatchResult, DispatchUnit, DispatchUnitStatus, EffortTier, GuardResult, IOptimizerDeps, KindFamily, KiSource, MilestoneDag, MilestoneGuardResult, MilestoneSnapshot, MilestoneStatus, ModelTier, OpenQuestion, OperationAction, OperationConflict, OperationDag, OperationSnapshot, OperationStatus, OperationType, OptimizationConfig, PairwiseOverlapMap, PlanKind, Provenance, ProviderConfig, ProviderType, RetryConfig, SentinelFanoutConfig, SentinelRole, Shape, ShapeCode, ShapeCodeSnapshot, ShapeConfig, ShapeConfigSnapshot, ShapeDoc, ShapeKind, ShapeNull, ShapeOpDag, ShapeOpSnapshot, ShapeOpType, ShapeSnapshot, ShapeStructuredOutput, SnapshotOptimization, Turn, ValidationError, ValidationResult, } from './lib/types.js';
+export { isValidOpForKind, VALID_OPS_BY_KIND, WRITE_CLASS_ACTIONS, } from './lib/types.js';
+export { assertValidDagJson, assertValidSnapshot, validateDagJson, validateSnapshot, } from './lib/validate.js';
+export { migrateDag } from './lib/migrate.js';

package/index.js

@@ -0,0 +1,5 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const D=new Set(["create","modify-signature","modify-body","add-export","remove-export","rename"]),x={function:new Set(["add-param","remove-param","rename-param","retype-param","change-param-optional","reorder-params","change-return"]),interface:new Set(["add-field","remove-field","rename-field","retype-field","change-field-optional","add-generic","remove-generic","constrain-generic","add-extends","remove-extends"]),type:new Set(["add-field","remove-field","retype-field"]),class:new Set(["add-field","remove-field","rename-field","retype-field","change-field-optional","add-param","add-generic","remove-generic","constrain-generic","add-extends","remove-extends"]),enum:new Set(["add-field","remove-field","rename-field"]),const:new Set(["add-var","remove-var","rename-var","change-default"]),config:new Set(["set-key","remove-key","rename-key","add-entry","remove-entry","update-entry","bump-version","update-checksum"]),env:new Set(["set-key","remove-key","rename-key"]),schema:new Set(["add-table","remove-table","add-column","remove-column","rename-column","retype-column","change-nullable","add-index","remove-index"]),manifest:new Set(["add-entry","remove-entry","bump-version"]),doc:new Set(["add-section","remove-section","rename-section","update-section"]),"structured-output":new Set([]),script:new Set(["add-param","remove-param","rename-param","retype-param","change-param-optional","reorder-params","change-return","add-field","remove-field","rename-field","retype-field","change-field-optional","add-generic","remove-generic","constrain-generic","add-extends","remove-extends","set-key","remove-key","rename-key","add-array-item","remove-array-item","add-var","remove-var","rename-var","change-default","add-section","remove-section","rename-section","update-section","add-table","remove-table","add-column","remove-column","rename-column","retype-column","change-nullable","add-index","remove-index","add-entry","remove-entry","update-entry","bump-version","update-checksum","add-export"])};function j(t,e){const i=x[t];return i?i.has(e):!1}const T=new Set(["pending","pending-surfaced","in_progress","complete","failed","skipped"]),q=new Set(["pending","in_progress","complete","failed","skipped"]),E=new Set(["automated","tool-call","generative"]),N=new Set(["function","interface","type","class","enum","const","script","config","env","schema","manifest","doc","structured-output"]);function f(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function d(t){return typeof t=="string"}function n(t,e,i){return{path:t,message:e,value:i}}function L(t){var l,y;const e=Object.keys(t),i=new Map,r=new Map;for(const s of e)i.set(s,0),r.set(s,[]);for(const s of e)for(const a of((l=t[s])==null?void 0:l.depends_on)??[])t[a]&&((y=r.get(a))==null||y.push(s),i.set(s,(i.get(s)??0)+1));const p=e.filter(s=>(i.get(s)??0)===0),c=new Set;for(;p.length>0;){const s=p.shift();if(s!==void 0){c.add(s);for(const a of r.get(s)??[]){const u=(i.get(a)??1)-1;i.set(a,u),u===0&&p.push(a)}}}return c.size!==e.length?e.filter(s=>!c.has(s)).map(s=>({slug:s})):null}function R(t,e){for(const i of t){if(!f(i))continue;const r=d(i.id)?i.id:"?",p=i.turns;if(!Array.isArray(p)){e.push(n(`dispatch_log[${r}].turns`,"must be an array",p));continue}for(let c=0;c<p.length;c++){const l=p[c],y=`dispatch_log[${r}].turns[${c}]`;if(!f(l)){e.push(n(y,"must be an object",l));continue}(typeof l.turn!="number"||!Number.isInteger(l.turn)||l.turn<1)&&e.push(n(`${y}.turn`,"must be a positive integer",l.turn)),typeof l.input_tokens!="number"&&e.push(n(`${y}.input_tokens`,"must be a number",l.input_tokens)),typeof l.output_tokens!="number"&&e.push(n(`${y}.output_tokens`,"must be a number",l.output_tokens)),d(l.t)||e.push(n(`${y}.t`,"must be a string",l.t));const s=l.model_calls;s!=null&&typeof s!="number"&&e.push(n(`${y}.model_calls`,"must be a number or null if present",s))}}}function O(t){const e=[];if(!f(t))return{valid:!1,errors:[n("","root must be an object")]};for(const c of["description","problem","approach","executor"]){const l=t[c];(!d(l)||l.trim()==="")&&e.push(n(c,"required string field missing/empty",l))}typeof t.schema_version!="number"&&e.push(n("schema_version","must be a number",t.schema_version));const i=t.plan_kind;i!=="brownfield"&&i!=="greenfield"&&e.push(n("plan_kind",'must be "brownfield" or "greenfield"',i)),Array.isArray(t.phases)?t.phases.length===0&&e.push(n("phases","must have at least one entry")):e.push(n("phases","must be an array",t.phases));const r=t.terminal;!d(r)&&!Array.isArray(r)&&e.push(n("terminal","must be a string or array",r)),Array.isArray(t.dispatch_log)?R(t.dispatch_log,e):e.push(n("dispatch_log","must be an array",t.dispatch_log)),f(t.optimization)||e.push(n("optimization","must be an object",t.optimization)),f(t.providers)||e.push(n("providers","must be an object",t.providers)),f(t.effort_max_tokens)||e.push(n("effort_max_tokens","must be an object",t.effort_max_tokens));const p=t.milestones;if(!f(p))e.push(n("milestones","must be an object",p));else{const c=Object.keys(p);c.length===0&&e.push(n("milestones","must have at least one entry"));const l=new Set(c);for(const u of c){const o=p[u];if(!f(o)){e.push(n(`milestones.${u}`,"must be an object",o));continue}if((!d(o.description)||o.description.trim()==="")&&e.push(n(`milestones.${u}.description`,"required string",o.description)),!Array.isArray(o.depends_on))e.push(n(`milestones.${u}.depends_on`,"must be an array",o.depends_on));else for(const _ of o.depends_on)d(_)?l.has(_)||e.push(n(`milestones.${u}.depends_on`,`unknown milestone "${_}"`)):e.push(n(`milestones.${u}.depends_on[]`,"must be a string",_));const b=o.phase;(!d(b)||b.trim()==="")&&e.push(n(`milestones.${u}.phase`,"required string",b)),(!d(o.authored_by)||o.authored_by.trim()==="")&&e.push(n(`milestones.${u}.authored_by`,"required string",o.authored_by));const m=o.model;m!=null&&!["Haiku","Sonnet","Opus"].includes(m)&&e.push(n(`milestones.${u}.model`,"invalid model tier",m));const h=o.effort;h!=null&&!["low","medium","high","xhigh","max"].includes(h)&&e.push(n(`milestones.${u}.effort`,"invalid effort tier",h)),o.two_stage!==void 0&&typeof o.two_stage!="boolean"&&e.push(n(`milestones.${u}.two_stage`,"must be a boolean",o.two_stage)),Array.isArray(o.read_only)||e.push(n(`milestones.${u}.read_only`,"must be an array",o.read_only))}const y=L(p);if(y)for(const{slug:u}of y)e.push(n(`milestones.${u}`,"dependency cycle detected"));if(d(r)&&!l.has(r))e.push(n("terminal",`unknown milestone "${r}"`));else if(Array.isArray(r))for(const u of r)l.has(u)||e.push(n("terminal[]",`unknown milestone "${u}"`));const s=t.operations,a=new Set;if(!Array.isArray(s)&&!f(s))e.push(n("operations","must be an array or object",s));else{const u=Array.isArray(s)?s:Object.values(s);for(const o of u){if(!f(o)){e.push(n("operations[]","must be an object",o));continue}const b=o.id;if(!d(b)){e.push(n("operations[?]","missing/invalid id",b));continue}const m=b;a.add(m);const h=o.milestone;d(h)?l.has(h)||e.push(n(`operations[${m}].milestone`,`unknown milestone "${h}"`)):e.push(n(`operations[${m}].milestone`,"required string",h));const _=o.type;d(_)&&!E.has(_)&&e.push(n(`operations[${m}].type`,"invalid type",_));const v=o.shape;if(f(v)){const g=v.kind;g!=null&&d(g)&&!N.has(g)&&e.push(n(`operations[${m}].shape.kind`,"invalid shape kind",g));const $=v.ops;if(Array.isArray($)&&d(g))for(let w=0;w<$.length;w++){const k=$[w];if(!f(k))continue;const A=k.op;d(A)&&!j(g,A)&&e.push(n(`operations[${m}].shape.ops[${w}]`,`op "${A}" not valid for kind "${g}"`))}}Array.isArray(o.depends_on)||e.push(n(`operations[${m}].depends_on`,"must be an array",o.depends_on))}for(const o of u){if(!f(o))continue;const b=o.id;if(!d(b))continue;const m=o.depends_on;if(Array.isArray(m))for(const h of m)d(h)&&!a.has(h)&&e.push(n(`operations[${b}].depends_on`,`unknown operation "${h}"`))}}}return{valid:e.length===0,errors:e}}function I(t){const e=[];if(!f(t))return{valid:!1,errors:[n("","root must be an object")]};for(const r of["snapshot_at","description"])d(t[r])||e.push(n(r,"required string field missing",t[r]));d(t.plan)||e.push(n("plan","required string",t.plan));const i=t.milestones;if(!f(i))e.push(n("milestones","must be an object",i));else{const r=Object.keys(i),p=new Set(r);for(const s of r){const a=i[s];if(!f(a)){e.push(n(`milestones.${s}`,"must be an object",a));continue}const u=a.eligible,o=a.pending;u===!0&&o!==null&&o!==void 0&&e.push(n(`milestones.${s}`,"D-07 violation: eligible=true but pending not null")),typeof u!="boolean"&&e.push(n(`milestones.${s}.eligible`,"must be boolean",u));const b=a.status;(!d(b)||!T.has(b))&&e.push(n(`milestones.${s}.status`,"invalid status",b));const m=a.wave;(typeof m!="number"||!Number.isInteger(m)||m<0)&&e.push(n(`milestones.${s}.wave`,"must be non-negative integer",m));const h=a.ki_estimate;h!=null&&typeof h!="number"&&e.push(n(`milestones.${s}.ki_estimate`,"must be number|null",h));for(const _ of["tokens_estimated","tokens_actual"]){const v=a[_];v!=null&&typeof v!="number"&&e.push(n(`milestones.${s}.${_}`,"must be number|null",v))}Array.isArray(a.artifacts)||e.push(n(`milestones.${s}.artifacts`,"must be an array",a.artifacts)),typeof a.si_bytes!="number"&&e.push(n(`milestones.${s}.si_bytes`,"must be a number",a.si_bytes))}const c=t.operations;if(!Array.isArray(c))e.push(n("operations","must be an array",c));else for(const s of c){if(!f(s))continue;const a=d(s.id)?s.id:"?",u=s.milestone;d(u)&&!p.has(u)&&e.push(n(`operations[${a}].milestone`,`unknown milestone "${u}"`));const o=s.status;(!d(o)||!q.has(o))&&e.push(n(`operations[${a}].status`,"invalid operation status",o)),Array.isArray(s.dispatch_ids)||e.push(n(`operations[${a}].dispatch_ids`,"must be an array",s.dispatch_ids)),typeof s.attempt_count!="number"&&e.push(n(`operations[${a}].attempt_count`,"must be a number",s.attempt_count)),Array.isArray(s.blast_radius)||e.push(n(`operations[${a}].blast_radius`,"must be an array",s.blast_radius))}const l=t.open_questions;if(!Array.isArray(l))e.push(n("open_questions","must be an array",l));else for(const s of l){if(!f(s))continue;const a=s.blocking;(!d(a)||!p.has(a))&&e.push(n("open_questions",`unknown blocking milestone "${a}"`)),typeof s.surfaced!="boolean"&&e.push(n(`open_questions[${s.id}]`,"surfaced must be boolean",s.surfaced)),typeof s.answered!="boolean"&&e.push(n(`open_questions[${s.id}]`,"answered must be boolean",s.answered))}const y=t.dispatch_units;if(y!==void 0)if(!Array.isArray(y))e.push(n("dispatch_units","must be an array if present",y));else for(const s of y){if(!f(s))continue;const a=s.fits_context_window;typeof a!="boolean"&&e.push(n(`dispatch_units[${s.id}]`,"fits_context_window must be boolean",a));const u=s.milestones;if(Array.isArray(u))for(const o of u)d(o)&&!p.has(o)&&e.push(n(`dispatch_units[${s.id}].milestones`,`unknown milestone "${o}"`))}f(t.pairwise_overlap)||e.push(n("pairwise_overlap","must be an object",t.pairwise_overlap))}return{valid:e.length===0,errors:e}}function K(t){const e=O(t);if(!e.valid)throw new Error(`DagJson validation failed:
+${e.errors.map(i=>`  ${i.path}: ${i.message}`).join(`
+`)}`)}function P(t){const e=I(t);if(!e.valid)throw new Error(`Snapshot validation failed:
+${e.errors.map(i=>`  ${i.path}: ${i.message}`).join(`
+`)}`)}const S=[{from:2,to:3,apply:t=>{!t.milestones&&t.nodes&&(t.milestones=t.nodes,delete t.nodes);const e=t.operations;e&&typeof e=="object"&&!Array.isArray(e)&&(t.operations=Object.values(e))}},{from:3,to:4,apply:t=>{(!t.providers||Object.keys(t.providers).length===0)&&(t.providers={Haiku:{type:"claudecli",model_id:"claude-haiku-4-5",env_secret:null,base_url:null,timeout_ms:6e4,retry_config:{retries:3,min_timeout:1e3,max_timeout:3e4,factor:2}},Sonnet:{type:"claudecli",model_id:"claude-sonnet-4-5",env_secret:null,base_url:null,timeout_ms:12e4,retry_config:{retries:3,min_timeout:1e3,max_timeout:3e4,factor:2}},Opus:{type:"claudecli",model_id:"claude-opus-4-5",env_secret:null,base_url:null,timeout_ms:3e5,retry_config:{retries:3,min_timeout:1e3,max_timeout:3e4,factor:2}}}),(!t.effort_max_tokens||Object.keys(t.effort_max_tokens).length===0)&&(t.effort_max_tokens={low:1024,medium:4096,high:8192,xhigh:16384,max:32768}),t.optimization||(t.optimization={sentinel_fanout:{enabled:!0,write_multiplier:1.25,read_multiplier:.1,hit_probability:.9},b_per_tier:{Haiku:8e3,Sonnet:15e3,Opus:27e3},context_window_per_tier:{Haiku:16e3,Sonnet:16e3,Opus:32e3},context_window_override:null,b_override:null});let e=[];Array.isArray(t.operations)?e=t.operations:t.operations&&typeof t.operations=="object"&&(e=Object.values(t.operations));for(const i of e)if(typeof i=="object"&&i!==null){const r=i;r.type===void 0&&(r.type="generative"),r.criteria===void 0&&(r.criteria=[]),r.tool===void 0&&(r.tool=null),r.args===void 0&&(r.args=null)}}}];function V(t,e,i){if(t===e)return;let r=t;for(const p of[...S].sort((c,l)=>c.from-l.from))if(p.from===r&&(p.apply(i),r=p.to,r===e)){i.schema_version=e;return}throw new Error(`migrateDag: no path from v${t} to v${e}. Available: [${S.map(p=>`v${p.from}→v${p.to}`).join(", ")}]`)}exports.VALID_OPS_BY_KIND=x;exports.WRITE_CLASS_ACTIONS=D;exports.assertValidDagJson=K;exports.assertValidSnapshot=P;exports.isValidOpForKind=j;exports.migrateDag=V;exports.validateDagJson=O;exports.validateSnapshot=I;

package/index.mjs

@@ -0,0 +1,667 @@
+const R = /* @__PURE__ */ new Set([
+  "create",
+  "modify-signature",
+  "modify-body",
+  "add-export",
+  "remove-export",
+  "rename"
+]), x = {
+  function: /* @__PURE__ */ new Set([
+    "add-param",
+    "remove-param",
+    "rename-param",
+    "retype-param",
+    "change-param-optional",
+    "reorder-params",
+    "change-return"
+  ]),
+  interface: /* @__PURE__ */ new Set([
+    "add-field",
+    "remove-field",
+    "rename-field",
+    "retype-field",
+    "change-field-optional",
+    "add-generic",
+    "remove-generic",
+    "constrain-generic",
+    "add-extends",
+    "remove-extends"
+  ]),
+  type: /* @__PURE__ */ new Set(["add-field", "remove-field", "retype-field"]),
+  class: /* @__PURE__ */ new Set([
+    "add-field",
+    "remove-field",
+    "rename-field",
+    "retype-field",
+    "change-field-optional",
+    "add-param",
+    "add-generic",
+    "remove-generic",
+    "constrain-generic",
+    "add-extends",
+    "remove-extends"
+  ]),
+  enum: /* @__PURE__ */ new Set(["add-field", "remove-field", "rename-field"]),
+  const: /* @__PURE__ */ new Set([
+    "add-var",
+    "remove-var",
+    "rename-var",
+    "change-default"
+  ]),
+  config: /* @__PURE__ */ new Set([
+    "set-key",
+    "remove-key",
+    "rename-key",
+    "add-entry",
+    "remove-entry",
+    "update-entry",
+    "bump-version",
+    "update-checksum"
+  ]),
+  env: /* @__PURE__ */ new Set(["set-key", "remove-key", "rename-key"]),
+  schema: /* @__PURE__ */ new Set([
+    "add-table",
+    "remove-table",
+    "add-column",
+    "remove-column",
+    "rename-column",
+    "retype-column",
+    "change-nullable",
+    "add-index",
+    "remove-index"
+  ]),
+  manifest: /* @__PURE__ */ new Set(["add-entry", "remove-entry", "bump-version"]),
+  doc: /* @__PURE__ */ new Set([
+    "add-section",
+    "remove-section",
+    "rename-section",
+    "update-section"
+  ]),
+  "structured-output": /* @__PURE__ */ new Set([]),
+  script: /* @__PURE__ */ new Set([
+    "add-param",
+    "remove-param",
+    "rename-param",
+    "retype-param",
+    "change-param-optional",
+    "reorder-params",
+    "change-return",
+    "add-field",
+    "remove-field",
+    "rename-field",
+    "retype-field",
+    "change-field-optional",
+    "add-generic",
+    "remove-generic",
+    "constrain-generic",
+    "add-extends",
+    "remove-extends",
+    "set-key",
+    "remove-key",
+    "rename-key",
+    "add-array-item",
+    "remove-array-item",
+    "add-var",
+    "remove-var",
+    "rename-var",
+    "change-default",
+    "add-section",
+    "remove-section",
+    "rename-section",
+    "update-section",
+    "add-table",
+    "remove-table",
+    "add-column",
+    "remove-column",
+    "rename-column",
+    "retype-column",
+    "change-nullable",
+    "add-index",
+    "remove-index",
+    "add-entry",
+    "remove-entry",
+    "update-entry",
+    "bump-version",
+    "update-checksum",
+    "add-export"
+  ])
+};
+function j(t, e) {
+  const i = x[t];
+  return i ? i.has(e) : !1;
+}
+const O = /* @__PURE__ */ new Set([
+  "pending",
+  "pending-surfaced",
+  "in_progress",
+  "complete",
+  "failed",
+  "skipped"
+]), I = /* @__PURE__ */ new Set([
+  "pending",
+  "in_progress",
+  "complete",
+  "failed",
+  "skipped"
+]), q = /* @__PURE__ */ new Set(["automated", "tool-call", "generative"]), D = /* @__PURE__ */ new Set([
+  "function",
+  "interface",
+  "type",
+  "class",
+  "enum",
+  "const",
+  "script",
+  "config",
+  "env",
+  "schema",
+  "manifest",
+  "doc",
+  "structured-output"
+]);
+function f(t) {
+  return typeof t == "object" && t !== null && !Array.isArray(t);
+}
+function c(t) {
+  return typeof t == "string";
+}
+function n(t, e, i) {
+  return { path: t, message: e, value: i };
+}
+function T(t) {
+  var l, y;
+  const e = Object.keys(t), i = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+  for (const s of e)
+    i.set(s, 0), r.set(s, []);
+  for (const s of e)
+    for (const a of ((l = t[s]) == null ? void 0 : l.depends_on) ?? [])
+      t[a] && ((y = r.get(a)) == null || y.push(s), i.set(s, (i.get(s) ?? 0) + 1));
+  const p = e.filter((s) => (i.get(s) ?? 0) === 0), d = /* @__PURE__ */ new Set();
+  for (; p.length > 0; ) {
+    const s = p.shift();
+    if (s !== void 0) {
+      d.add(s);
+      for (const a of r.get(s) ?? []) {
+        const u = (i.get(a) ?? 1) - 1;
+        i.set(a, u), u === 0 && p.push(a);
+      }
+    }
+  }
+  return d.size !== e.length ? e.filter((s) => !d.has(s)).map((s) => ({ slug: s })) : null;
+}
+function E(t, e) {
+  for (const i of t) {
+    if (!f(i))
+      continue;
+    const r = c(i.id) ? i.id : "?", p = i.turns;
+    if (!Array.isArray(p)) {
+      e.push(
+        n(`dispatch_log[${r}].turns`, "must be an array", p)
+      );
+      continue;
+    }
+    for (let d = 0; d < p.length; d++) {
+      const l = p[d], y = `dispatch_log[${r}].turns[${d}]`;
+      if (!f(l)) {
+        e.push(n(y, "must be an object", l));
+        continue;
+      }
+      (typeof l.turn != "number" || !Number.isInteger(l.turn) || l.turn < 1) && e.push(n(`${y}.turn`, "must be a positive integer", l.turn)), typeof l.input_tokens != "number" && e.push(
+        n(`${y}.input_tokens`, "must be a number", l.input_tokens)
+      ), typeof l.output_tokens != "number" && e.push(
+        n(`${y}.output_tokens`, "must be a number", l.output_tokens)
+      ), c(l.t) || e.push(n(`${y}.t`, "must be a string", l.t));
+      const s = l.model_calls;
+      s != null && typeof s != "number" && e.push(
+        n(
+          `${y}.model_calls`,
+          "must be a number or null if present",
+          s
+        )
+      );
+    }
+  }
+}
+function N(t) {
+  const e = [];
+  if (!f(t))
+    return { valid: !1, errors: [n("", "root must be an object")] };
+  for (const d of ["description", "problem", "approach", "executor"]) {
+    const l = t[d];
+    (!c(l) || l.trim() === "") && e.push(n(d, "required string field missing/empty", l));
+  }
+  typeof t.schema_version != "number" && e.push(
+    n("schema_version", "must be a number", t.schema_version)
+  );
+  const i = t.plan_kind;
+  i !== "brownfield" && i !== "greenfield" && e.push(n("plan_kind", 'must be "brownfield" or "greenfield"', i)), Array.isArray(t.phases) ? t.phases.length === 0 && e.push(n("phases", "must have at least one entry")) : e.push(n("phases", "must be an array", t.phases));
+  const r = t.terminal;
+  !c(r) && !Array.isArray(r) && e.push(n("terminal", "must be a string or array", r)), Array.isArray(t.dispatch_log) ? E(t.dispatch_log, e) : e.push(n("dispatch_log", "must be an array", t.dispatch_log)), f(t.optimization) || e.push(n("optimization", "must be an object", t.optimization)), f(t.providers) || e.push(n("providers", "must be an object", t.providers)), f(t.effort_max_tokens) || e.push(
+    n("effort_max_tokens", "must be an object", t.effort_max_tokens)
+  );
+  const p = t.milestones;
+  if (!f(p))
+    e.push(n("milestones", "must be an object", p));
+  else {
+    const d = Object.keys(p);
+    d.length === 0 && e.push(n("milestones", "must have at least one entry"));
+    const l = new Set(d);
+    for (const u of d) {
+      const o = p[u];
+      if (!f(o)) {
+        e.push(n(`milestones.${u}`, "must be an object", o));
+        continue;
+      }
+      if ((!c(o.description) || o.description.trim() === "") && e.push(
+        n(
+          `milestones.${u}.description`,
+          "required string",
+          o.description
+        )
+      ), !Array.isArray(o.depends_on))
+        e.push(
+          n(
+            `milestones.${u}.depends_on`,
+            "must be an array",
+            o.depends_on
+          )
+        );
+      else
+        for (const _ of o.depends_on)
+          c(_) ? l.has(_) || e.push(
+            n(`milestones.${u}.depends_on`, `unknown milestone "${_}"`)
+          ) : e.push(
+            n(`milestones.${u}.depends_on[]`, "must be a string", _)
+          );
+      const b = o.phase;
+      (!c(b) || b.trim() === "") && e.push(n(`milestones.${u}.phase`, "required string", b)), (!c(o.authored_by) || o.authored_by.trim() === "") && e.push(
+        n(
+          `milestones.${u}.authored_by`,
+          "required string",
+          o.authored_by
+        )
+      );
+      const m = o.model;
+      m != null && !["Haiku", "Sonnet", "Opus"].includes(m) && e.push(
+        n(`milestones.${u}.model`, "invalid model tier", m)
+      );
+      const h = o.effort;
+      h != null && !["low", "medium", "high", "xhigh", "max"].includes(h) && e.push(
+        n(`milestones.${u}.effort`, "invalid effort tier", h)
+      ), o.two_stage !== void 0 && typeof o.two_stage != "boolean" && e.push(
+        n(
+          `milestones.${u}.two_stage`,
+          "must be a boolean",
+          o.two_stage
+        )
+      ), Array.isArray(o.read_only) || e.push(
+        n(
+          `milestones.${u}.read_only`,
+          "must be an array",
+          o.read_only
+        )
+      );
+    }
+    const y = T(
+      p
+    );
+    if (y)
+      for (const { slug: u } of y)
+        e.push(n(`milestones.${u}`, "dependency cycle detected"));
+    if (c(r) && !l.has(r))
+      e.push(n("terminal", `unknown milestone "${r}"`));
+    else if (Array.isArray(r))
+      for (const u of r)
+        l.has(u) || e.push(n("terminal[]", `unknown milestone "${u}"`));
+    const s = t.operations, a = /* @__PURE__ */ new Set();
+    if (!Array.isArray(s) && !f(s))
+      e.push(n("operations", "must be an array or object", s));
+    else {
+      const u = Array.isArray(s) ? s : Object.values(s);
+      for (const o of u) {
+        if (!f(o)) {
+          e.push(n("operations[]", "must be an object", o));
+          continue;
+        }
+        const b = o.id;
+        if (!c(b)) {
+          e.push(n("operations[?]", "missing/invalid id", b));
+          continue;
+        }
+        const m = b;
+        a.add(m);
+        const h = o.milestone;
+        c(h) ? l.has(h) || e.push(
+          n(`operations[${m}].milestone`, `unknown milestone "${h}"`)
+        ) : e.push(
+          n(`operations[${m}].milestone`, "required string", h)
+        );
+        const _ = o.type;
+        c(_) && !q.has(_) && e.push(n(`operations[${m}].type`, "invalid type", _));
+        const v = o.shape;
+        if (f(v)) {
+          const g = v.kind;
+          g != null && c(g) && !D.has(g) && e.push(
+            n(`operations[${m}].shape.kind`, "invalid shape kind", g)
+          );
+          const $ = v.ops;
+          if (Array.isArray($) && c(g))
+            for (let w = 0; w < $.length; w++) {
+              const A = $[w];
+              if (!f(A))
+                continue;
+              const k = A.op;
+              c(k) && !j(g, k) && e.push(
+                n(
+                  `operations[${m}].shape.ops[${w}]`,
+                  `op "${k}" not valid for kind "${g}"`
+                )
+              );
+            }
+        }
+        Array.isArray(o.depends_on) || e.push(
+          n(
+            `operations[${m}].depends_on`,
+            "must be an array",
+            o.depends_on
+          )
+        );
+      }
+      for (const o of u) {
+        if (!f(o))
+          continue;
+        const b = o.id;
+        if (!c(b))
+          continue;
+        const m = o.depends_on;
+        if (Array.isArray(m))
+          for (const h of m)
+            c(h) && !a.has(h) && e.push(
+              n(
+                `operations[${b}].depends_on`,
+                `unknown operation "${h}"`
+              )
+            );
+      }
+    }
+  }
+  return { valid: e.length === 0, errors: e };
+}
+function L(t) {
+  const e = [];
+  if (!f(t))
+    return { valid: !1, errors: [n("", "root must be an object")] };
+  for (const r of ["snapshot_at", "description"])
+    c(t[r]) || e.push(n(r, "required string field missing", t[r]));
+  c(t.plan) || e.push(n("plan", "required string", t.plan));
+  const i = t.milestones;
+  if (!f(i))
+    e.push(n("milestones", "must be an object", i));
+  else {
+    const r = Object.keys(i), p = new Set(r);
+    for (const s of r) {
+      const a = i[s];
+      if (!f(a)) {
+        e.push(n(`milestones.${s}`, "must be an object", a));
+        continue;
+      }
+      const u = a.eligible, o = a.pending;
+      u === !0 && o !== null && o !== void 0 && e.push(
+        n(
+          `milestones.${s}`,
+          "D-07 violation: eligible=true but pending not null"
+        )
+      ), typeof u != "boolean" && e.push(
+        n(`milestones.${s}.eligible`, "must be boolean", u)
+      );
+      const b = a.status;
+      (!c(b) || !O.has(b)) && e.push(n(`milestones.${s}.status`, "invalid status", b));
+      const m = a.wave;
+      (typeof m != "number" || !Number.isInteger(m) || m < 0) && e.push(
+        n(`milestones.${s}.wave`, "must be non-negative integer", m)
+      );
+      const h = a.ki_estimate;
+      h != null && typeof h != "number" && e.push(
+        n(`milestones.${s}.ki_estimate`, "must be number|null", h)
+      );
+      for (const _ of ["tokens_estimated", "tokens_actual"]) {
+        const v = a[_];
+        v != null && typeof v != "number" && e.push(n(`milestones.${s}.${_}`, "must be number|null", v));
+      }
+      Array.isArray(a.artifacts) || e.push(
+        n(
+          `milestones.${s}.artifacts`,
+          "must be an array",
+          a.artifacts
+        )
+      ), typeof a.si_bytes != "number" && e.push(
+        n(`milestones.${s}.si_bytes`, "must be a number", a.si_bytes)
+      );
+    }
+    const d = t.operations;
+    if (!Array.isArray(d))
+      e.push(n("operations", "must be an array", d));
+    else
+      for (const s of d) {
+        if (!f(s))
+          continue;
+        const a = c(s.id) ? s.id : "?", u = s.milestone;
+        c(u) && !p.has(u) && e.push(
+          n(
+            `operations[${a}].milestone`,
+            `unknown milestone "${u}"`
+          )
+        );
+        const o = s.status;
+        (!c(o) || !I.has(o)) && e.push(
+          n(
+            `operations[${a}].status`,
+            "invalid operation status",
+            o
+          )
+        ), Array.isArray(s.dispatch_ids) || e.push(
+          n(
+            `operations[${a}].dispatch_ids`,
+            "must be an array",
+            s.dispatch_ids
+          )
+        ), typeof s.attempt_count != "number" && e.push(
+          n(
+            `operations[${a}].attempt_count`,
+            "must be a number",
+            s.attempt_count
+          )
+        ), Array.isArray(s.blast_radius) || e.push(
+          n(
+            `operations[${a}].blast_radius`,
+            "must be an array",
+            s.blast_radius
+          )
+        );
+      }
+    const l = t.open_questions;
+    if (!Array.isArray(l))
+      e.push(n("open_questions", "must be an array", l));
+    else
+      for (const s of l) {
+        if (!f(s))
+          continue;
+        const a = s.blocking;
+        (!c(a) || !p.has(a)) && e.push(
+          n("open_questions", `unknown blocking milestone "${a}"`)
+        ), typeof s.surfaced != "boolean" && e.push(
+          n(
+            `open_questions[${s.id}]`,
+            "surfaced must be boolean",
+            s.surfaced
+          )
+        ), typeof s.answered != "boolean" && e.push(
+          n(
+            `open_questions[${s.id}]`,
+            "answered must be boolean",
+            s.answered
+          )
+        );
+      }
+    const y = t.dispatch_units;
+    if (y !== void 0)
+      if (!Array.isArray(y))
+        e.push(
+          n("dispatch_units", "must be an array if present", y)
+        );
+      else
+        for (const s of y) {
+          if (!f(s))
+            continue;
+          const a = s.fits_context_window;
+          typeof a != "boolean" && e.push(
+            n(
+              `dispatch_units[${s.id}]`,
+              "fits_context_window must be boolean",
+              a
+            )
+          );
+          const u = s.milestones;
+          if (Array.isArray(u))
+            for (const o of u)
+              c(o) && !p.has(o) && e.push(
+                n(
+                  `dispatch_units[${s.id}].milestones`,
+                  `unknown milestone "${o}"`
+                )
+              );
+        }
+    f(t.pairwise_overlap) || e.push(
+      n(
+        "pairwise_overlap",
+        "must be an object",
+        t.pairwise_overlap
+      )
+    );
+  }
+  return { valid: e.length === 0, errors: e };
+}
+function z(t) {
+  const e = N(t);
+  if (!e.valid)
+    throw new Error(
+      `DagJson validation failed:
+${e.errors.map((i) => `  ${i.path}: ${i.message}`).join(`
+`)}`
+    );
+}
+function H(t) {
+  const e = L(t);
+  if (!e.valid)
+    throw new Error(
+      `Snapshot validation failed:
+${e.errors.map((i) => `  ${i.path}: ${i.message}`).join(`
+`)}`
+    );
+}
+const S = [
+  {
+    from: 2,
+    to: 3,
+    apply: (t) => {
+      !t.milestones && t.nodes && (t.milestones = t.nodes, delete t.nodes);
+      const e = t.operations;
+      e && typeof e == "object" && !Array.isArray(e) && (t.operations = Object.values(e));
+    }
+  },
+  {
+    from: 3,
+    to: 4,
+    apply: (t) => {
+      (!t.providers || Object.keys(t.providers).length === 0) && (t.providers = {
+        Haiku: {
+          type: "claudecli",
+          model_id: "claude-haiku-4-5",
+          env_secret: null,
+          base_url: null,
+          timeout_ms: 6e4,
+          retry_config: {
+            retries: 3,
+            min_timeout: 1e3,
+            max_timeout: 3e4,
+            factor: 2
+          }
+        },
+        Sonnet: {
+          type: "claudecli",
+          model_id: "claude-sonnet-4-5",
+          env_secret: null,
+          base_url: null,
+          timeout_ms: 12e4,
+          retry_config: {
+            retries: 3,
+            min_timeout: 1e3,
+            max_timeout: 3e4,
+            factor: 2
+          }
+        },
+        Opus: {
+          type: "claudecli",
+          model_id: "claude-opus-4-5",
+          env_secret: null,
+          base_url: null,
+          timeout_ms: 3e5,
+          retry_config: {
+            retries: 3,
+            min_timeout: 1e3,
+            max_timeout: 3e4,
+            factor: 2
+          }
+        }
+      }), (!t.effort_max_tokens || Object.keys(t.effort_max_tokens).length === 0) && (t.effort_max_tokens = {
+        low: 1024,
+        medium: 4096,
+        high: 8192,
+        xhigh: 16384,
+        max: 32768
+      }), t.optimization || (t.optimization = {
+        sentinel_fanout: {
+          enabled: !0,
+          write_multiplier: 1.25,
+          read_multiplier: 0.1,
+          hit_probability: 0.9
+        },
+        b_per_tier: { Haiku: 8e3, Sonnet: 15e3, Opus: 27e3 },
+        context_window_per_tier: { Haiku: 16e3, Sonnet: 16e3, Opus: 32e3 },
+        context_window_override: null,
+        b_override: null
+      });
+      let e = [];
+      Array.isArray(t.operations) ? e = t.operations : t.operations && typeof t.operations == "object" && (e = Object.values(t.operations));
+      for (const i of e)
+        if (typeof i == "object" && i !== null) {
+          const r = i;
+          r.type === void 0 && (r.type = "generative"), r.criteria === void 0 && (r.criteria = []), r.tool === void 0 && (r.tool = null), r.args === void 0 && (r.args = null);
+        }
+    }
+  }
+];
+function K(t, e, i) {
+  if (t === e)
+    return;
+  let r = t;
+  for (const p of [...S].sort((d, l) => d.from - l.from))
+    if (p.from === r && (p.apply(i), r = p.to, r === e)) {
+      i.schema_version = e;
+      return;
+    }
+  throw new Error(
+    `migrateDag: no path from v${t} to v${e}. Available: [${S.map(
+      (p) => `v${p.from}→v${p.to}`
+    ).join(", ")}]`
+  );
+}
+export {
+  x as VALID_OPS_BY_KIND,
+  R as WRITE_CLASS_ACTIONS,
+  z as assertValidDagJson,
+  H as assertValidSnapshot,
+  j as isValidOpForKind,
+  K as migrateDag,
+  N as validateDagJson,
+  L as validateSnapshot
+};

package/lib/migrate.d.ts

@@ -0,0 +1 @@
+export declare function migrateDag(fromVersion: number, toVersion: number, dag: Record<string, unknown>): void;

package/lib/types.d.ts

@@ -0,0 +1,358 @@
+/**
+ * types.ts — Complete TypeScript type system for the dispatch plan ecosystem.
+ *
+ * Source: docs/plan/dispatch-completion/superseded/dispatch-optimizer/PROPOSED_DAG_STRUCTURE.md
+ * Design decisions: D-01 through D-18 in DECISIONS.md
+ *
+ * Field provenance: dag | derived | scheduler | optimizer | clock | gitnexus
+ * Zero dependencies. Pure TypeScript. platform:shared.
+ */
+/** D-03 + D-18 — which executor the orchestrator routes this operation to. */
+export type OperationType = 'automated' | 'tool-call' | 'generative';
+export type OperationAction = 'create' | 'delete' | 'move' | 'rename' | 'modify-signature' | 'modify-body' | 'add-export' | 'remove-export' | 'guard' | 'exec' | 'dag.inject' | 'dag.wait' | 'dag.add-milestone' | 'dag.set-field' | 'dag.clear-pending' | 'dag.append-dispatch-log' | 'fs.move' | 'fs.delete' | 'fs.scaffold';
+export declare const WRITE_CLASS_ACTIONS: ReadonlySet<OperationAction>;
+export type CodeKind = 'function' | 'interface' | 'type' | 'class' | 'enum' | 'const' | 'script';
+export type ConfigKind = 'config' | 'env' | 'schema' | 'manifest';
+export type ShapeKind = CodeKind | ConfigKind | 'doc' | 'structured-output';
+export type KindFamily = 'code-config' | 'doc' | 'structured' | 'tool-call';
+export type MilestoneStatus = 'pending' | 'pending-surfaced' | 'in_progress' | 'complete' | 'failed' | 'skipped';
+export type DispatchUnitStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
+export type OperationStatus = 'pending' | 'in_progress' | 'complete' | 'failed' | 'skipped';
+export type GuardResult = 'pass' | 'fail';
+export type MilestoneGuardResult = 'pass' | 'fail' | 'pending';
+export type Provenance = 'gitnexus' | 'manual' | 'assumed' | 'vendored';
+export type Confidence = 'verified' | 'vendored' | 'documented' | 'assumed';
+export type KiSource = 'estimate' | 'calibrated' | 'actual';
+export type DispatchKind = 'planning' | 'execution';
+export type ProviderType = 'anthropic' | 'openai' | 'claudecli';
+export type SentinelRole = 'prewarm' | 'payload' | 'solo';
+export type ModelTier = 'Haiku' | 'Sonnet' | 'Opus';
+export type EffortTier = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+export type PlanKind = 'brownfield' | 'greenfield';
+export type ShapeOpType = 'add-param' | 'remove-param' | 'rename-param' | 'retype-param' | 'change-param-optional' | 'reorder-params' | 'change-return' | 'add-field' | 'remove-field' | 'rename-field' | 'retype-field' | 'change-field-optional' | 'add-generic' | 'remove-generic' | 'constrain-generic' | 'add-extends' | 'remove-extends' | 'set-key' | 'remove-key' | 'rename-key' | 'add-array-item' | 'remove-array-item' | 'add-var' | 'remove-var' | 'rename-var' | 'change-default' | 'add-section' | 'remove-section' | 'rename-section' | 'update-section' | 'add-table' | 'remove-table' | 'add-column' | 'remove-column' | 'rename-column' | 'retype-column' | 'change-nullable' | 'add-index' | 'remove-index' | 'add-entry' | 'remove-entry' | 'update-entry' | 'bump-version' | 'update-checksum' | 'add-export' | 'remove-export';
+export declare const VALID_OPS_BY_KIND: Record<string, ReadonlySet<ShapeOpType>>;
+export declare function isValidOpForKind(kind: string, op: ShapeOpType): boolean;
+export interface ShapeOpDag {
+    op: ShapeOpType;
+    target: string | null;
+    to: string | null;
+    position: number | null;
+    required: boolean | null;
+}
+export interface ShapeOpSnapshot extends ShapeOpDag {
+    from: string | null;
+    breaking: boolean | null;
+    severity: 'error' | 'warning' | 'info' | null;
+}
+export interface ShapeCode {
+    kind: CodeKind;
+    ops: ShapeOpDag[];
+    description?: null;
+    objective?: null;
+    required_sections?: null;
+    schema?: null;
+}
+export interface ShapeConfig {
+    kind: ConfigKind;
+    ops: ShapeOpDag[];
+    description?: null;
+    objective?: null;
+    required_sections?: null;
+    schema?: null;
+}
+export interface ShapeDoc {
+    kind: 'doc';
+    ops?: null;
+    description: string;
+    objective: string;
+    required_sections: string[];
+    schema?: null;
+}
+export interface ShapeStructuredOutput {
+    kind: 'structured-output';
+    ops?: null;
+    description?: null;
+    objective?: null;
+    required_sections?: null;
+    schema: Record<string, unknown>;
+}
+export interface ShapeNull {
+    kind: null;
+    ops?: null;
+    description?: null;
+    objective?: null;
+    required_sections?: null;
+    schema?: null;
+}
+export type Shape = ShapeCode | ShapeConfig | ShapeDoc | ShapeStructuredOutput | ShapeNull;
+export interface ShapeCodeSnapshot extends Omit<ShapeCode, 'ops'> {
+    ops: ShapeOpSnapshot[];
+}
+export interface ShapeConfigSnapshot extends Omit<ShapeConfig, 'ops'> {
+    ops: ShapeOpSnapshot[];
+}
+export type ShapeSnapshot = ShapeCodeSnapshot | ShapeConfigSnapshot | ShapeDoc | ShapeStructuredOutput | ShapeNull;
+export interface BlastRadiusEntry {
+    file: string;
+    symbol: string;
+    impact: 'implements' | 'calls' | 'imports' | 'extends' | 're-exports' | 'overrides';
+    consumer: 'current' | 'future';
+}
+export interface OperationConflict {
+    detected: boolean;
+    competing_op: string | null;
+    op_key: string | null;
+    resolution: 'safe-merge' | 'warning' | 'error' | null;
+}
+export interface RetryConfig {
+    retries: number;
+    min_timeout: number;
+    max_timeout: number;
+    factor: number;
+}
+export interface ProviderConfig {
+    type: ProviderType;
+    model_id: string;
+    env_secret: string | null;
+    base_url: string | null;
+    timeout_ms: number;
+    retry_config: RetryConfig;
+}
+export interface Turn {
+    turn: number;
+    input_tokens: number;
+    output_tokens: number;
+    t: string;
+    /**
+     * Number of real model calls this synthesized turn represents. Added for
+     * DEBT-DISPATCH-008: agent-mcp's MCP surface exposes only aggregate usage
+     * per task (no per-turn breakdown — see agent-runner.ts `SynthesizedTurn`/
+     * `DispatchUsageReport`), so a dispatcher collapses a task's entire usage
+     * into ONE `Turn` and needs somewhere to carry `modelCalls` through.
+     * Optional and nullable for backward compatibility: every dag.json written
+     * before this field existed — and any producer that doesn't track model
+     * call counts — remains valid without it.
+     */
+    model_calls?: number | null;
+}
+export interface DispatchResult {
+    op_id: string;
+    status: 'complete' | 'failed' | 'skipped';
+    guard_result: GuardResult | null;
+    guard_output: string | null;
+    guard_ran_at: string | null;
+    /**
+     * Real outcome payload for `type: "tool-call"` operations (BUG-DISPATCH-EXEC-001
+     * / D-13, D-18). `null`/absent for every other op kind (generative,
+     * automated-guard). On success, the tool handler's own return value (e.g.
+     * `{ path, to }` for `fs.move`, `{ slug }` for `dag.add-milestone`). On
+     * failure, `{ error: string }` — never a silent 'skipped' with no payload.
+     * Optional for backward compatibility: every `dispatch_log` entry written
+     * before this field existed remains valid without it.
+     */
+    tool_result?: unknown | null;
+}
+export interface DispatchNote {
+    level: 'info' | 'warn' | 'error';
+    text: string;
+}
+export interface DispatchLogEntry {
+    id: string;
+    kind: DispatchKind;
+    provider: 'anthropic' | 'openai' | 'deepseek' | 'google' | 'local' | 'claudecli' | 'teammate';
+    model: string | null;
+    agent: string;
+    effort: EffortTier | null;
+    started_at: string;
+    completed_at: string | null;
+    operations: string[];
+    turns: Turn[];
+    results: DispatchResult[];
+    notes: DispatchNote[];
+}
+export interface OperationDag {
+    id: string;
+    milestone: string;
+    depends_on: string[];
+    type: OperationType;
+    action: OperationAction;
+    file: string | null;
+    symbol: string | null;
+    provenance: Provenance | null;
+    confidence: Confidence | null;
+    audit_check: string | null;
+    criteria: string[];
+    tool: string | null;
+    args: Record<string, unknown> | null;
+    guard: string | null;
+    to_file: string | null;
+    to_symbol: string | null;
+    ki_estimate: number | null;
+    ki_source: KiSource | null;
+    authored_by: string;
+    status: OperationStatus;
+    shape: Shape | null;
+}
+export interface OperationSnapshot extends Omit<OperationDag, 'shape'> {
+    shape: ShapeSnapshot | null;
+    dispatch_ids: string[];
+    attempt_count: number;
+    guard_result: GuardResult | null;
+    guard_output: string | null;
+    guard_ran_at: string | null;
+    blast_radius: BlastRadiusEntry[];
+    conflict: OperationConflict;
+    tokens_actual: number | null;
+}
+export interface MilestoneDag {
+    description: string;
+    rationale?: string;
+    authored_by: string;
+    pending: string | null;
+    triggered_by: string | null;
+    phase: string;
+    depends_on: string[];
+    agent: string | null;
+    model: ModelTier | null;
+    effort: EffortTier | null;
+    two_stage: boolean;
+    read_only: string[];
+    guard: string | null;
+}
+export interface CrossPlanDep {
+    plan: string;
+    milestone: string;
+}
+export type PairwiseOverlapMap = Record<string, number>;
+export interface OpenQuestion {
+    id: string;
+    text: string;
+    blocking: string;
+    surfaced: boolean;
+    raised_at_dispatch: string | null;
+    raised_at_turn: number | null;
+    answered: boolean;
+    answer: string | null;
+}
+export interface MilestoneSnapshot extends MilestoneDag {
+    context: string;
+    wave: number;
+    eligible: boolean;
+    status: MilestoneStatus;
+    started_at: string | null;
+    completed_at: string | null;
+    guard_result: MilestoneGuardResult | null;
+    guard_output: string | null;
+    artifacts: string[];
+    si_bytes: number;
+    ki_estimate: number | null;
+    tokens_estimated: number | null;
+    tokens_actual: number | null;
+}
+export interface SentinelFanoutConfig {
+    enabled: boolean;
+    write_multiplier: number;
+    read_multiplier: number;
+    hit_probability: number;
+}
+export interface OptimizationConfig {
+    sentinel_fanout: SentinelFanoutConfig;
+    b_per_tier: Record<string, number | null>;
+    context_window_per_tier: Record<string, number>;
+    context_window_override: Record<string, number> | null;
+    b_override: Record<string, number> | null;
+}
+export interface DagJson {
+    schema_version: number;
+    plan_kind: PlanKind;
+    description: string;
+    problem: string;
+    approach: string;
+    executor: string;
+    executor_model?: ModelTier;
+    executor_effort?: EffortTier;
+    phases: string[];
+    terminal: string | string[];
+    assumed_baseline?: string[] | Record<string, unknown>;
+    cross_plan_deps?: CrossPlanDep[];
+    optimization: OptimizationConfig;
+    providers: Record<string, ProviderConfig>;
+    effort_max_tokens: Record<string, number>;
+    milestones: Record<string, MilestoneDag>;
+    operations: OperationDag[] | Record<string, OperationDag>;
+    dispatch_log: DispatchLogEntry[];
+}
+export interface SnapshotOptimization {
+    tokens_naive: number | null;
+    sentinel_fanout: SentinelFanoutConfig;
+    context_window_override: Record<string, number> | null;
+    b_override: Record<string, number> | null;
+    b_per_tier: Record<string, number | null>;
+    b_eff_per_tier: Record<string, number | null>;
+    context_window_per_tier: Record<string, number>;
+}
+export interface DagSnapshot {
+    snapshot_at: string;
+    snapshot_version: number;
+    plan: string;
+    schema_version: number;
+    plan_kind: PlanKind;
+    description: string;
+    problem: string;
+    approach: string;
+    executor: string;
+    executor_model?: ModelTier;
+    executor_effort?: EffortTier;
+    phases: string[];
+    terminal: string | string[];
+    assumed_baseline?: string[] | Record<string, unknown>;
+    cross_plan_deps?: CrossPlanDep[];
+    optimization: SnapshotOptimization;
+    milestones: Record<string, MilestoneSnapshot>;
+    operations: OperationSnapshot[];
+    pairwise_overlap: PairwiseOverlapMap;
+    dispatch_units?: DispatchUnit[];
+    open_questions: OpenQuestion[];
+}
+export interface DispatchUnit {
+    id: string;
+    milestones: string[];
+    operations: string[];
+    model: ModelTier | null;
+    effort: EffortTier | null;
+    two_stage: boolean;
+    provider: ProviderConfig | null;
+    agent_name: string;
+    mcp_servers: Record<string, unknown> | null;
+    resolved_max_tokens: number | null;
+    background: true;
+    prompt: string | null;
+    context_files: string[];
+    si_bytes: number;
+    tokens_estimated: number | null;
+    fits_context_window: boolean;
+    sentinel_role: SentinelRole | null;
+    dispatch_log_id: string | null;
+    remote_task_id: string | null;
+    result: string | null;
+    status: DispatchUnitStatus;
+    started_at: string | null;
+    completed_at: string | null;
+    tokens_actual: number | null;
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+    value?: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export interface IOptimizerDeps {
+    bPerTier: Record<string, number>;
+    contextWindowPerTier: Record<string, number>;
+    fileSizes?: (paths: string[]) => Map<string, number>;
+    readFiles?: (paths: string[]) => Map<string, string>;
+    dispatchLog?: DispatchLogEntry[];
+}

package/lib/validate.d.ts

@@ -0,0 +1,6 @@
+import { DagJson, DagSnapshot, ValidationResult } from './types.js';
+
+export declare function validateDagJson(dag: unknown): ValidationResult;
+export declare function validateSnapshot(snapshot: unknown): ValidationResult;
+export declare function assertValidDagJson(dag: unknown): asserts dag is DagJson;
+export declare function assertValidSnapshot(s: unknown): asserts s is DagSnapshot;

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@adhd/dispatch-base-spec",
+  "version": "0.0.1",
+  "dependencies": {},
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}