@adhd/dispatch-core-optimizer 0.0.1

package/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/index.js

@@ -0,0 +1,10 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const de=new Set(["create","modify-signature","modify-body","add-export","remove-export","rename"]),me=new Set(["pending","pending-surfaced","in_progress","complete","failed","skipped"]),_e=new Set(["pending","in_progress","complete","failed","skipped"]);function S(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function O(e){return typeof e=="string"}function h(e,t,n){return{path:e,message:t,value:n}}function ge(e){const t=[];if(!S(e))return{valid:!1,errors:[h("","root must be an object")]};for(const o of["snapshot_at","description"])O(e[o])||t.push(h(o,"required string field missing",e[o]));O(e.plan)||t.push(h("plan","required string",e.plan));const n=e.milestones;if(!S(n))t.push(h("milestones","must be an object",n));else{const o=Object.keys(n),i=new Set(o);for(const s of o){const r=n[s];if(!S(r)){t.push(h(`milestones.${s}`,"must be an object",r));continue}const c=r.eligible,u=r.pending;c===!0&&u!==null&&u!==void 0&&t.push(h(`milestones.${s}`,"D-07 violation: eligible=true but pending not null")),typeof c!="boolean"&&t.push(h(`milestones.${s}.eligible`,"must be boolean",c));const p=r.status;(!O(p)||!me.has(p))&&t.push(h(`milestones.${s}.status`,"invalid status",p));const _=r.wave;(typeof _!="number"||!Number.isInteger(_)||_<0)&&t.push(h(`milestones.${s}.wave`,"must be non-negative integer",_));const b=r.ki_estimate;b!=null&&typeof b!="number"&&t.push(h(`milestones.${s}.ki_estimate`,"must be number|null",b));for(const v of["tokens_estimated","tokens_actual"]){const y=r[v];y!=null&&typeof y!="number"&&t.push(h(`milestones.${s}.${v}`,"must be number|null",y))}Array.isArray(r.artifacts)||t.push(h(`milestones.${s}.artifacts`,"must be an array",r.artifacts)),typeof r.si_bytes!="number"&&t.push(h(`milestones.${s}.si_bytes`,"must be a number",r.si_bytes))}const l=e.operations;if(!Array.isArray(l))t.push(h("operations","must be an array",l));else for(const s of l){if(!S(s))continue;const r=O(s.id)?s.id:"?",c=s.milestone;O(c)&&!i.has(c)&&t.push(h(`operations[${r}].milestone`,`unknown milestone "${c}"`));const u=s.status;(!O(u)||!_e.has(u))&&t.push(h(`operations[${r}].status`,"invalid operation status",u)),Array.isArray(s.dispatch_ids)||t.push(h(`operations[${r}].dispatch_ids`,"must be an array",s.dispatch_ids)),typeof s.attempt_count!="number"&&t.push(h(`operations[${r}].attempt_count`,"must be a number",s.attempt_count)),Array.isArray(s.blast_radius)||t.push(h(`operations[${r}].blast_radius`,"must be an array",s.blast_radius))}const f=e.open_questions;if(!Array.isArray(f))t.push(h("open_questions","must be an array",f));else for(const s of f){if(!S(s))continue;const r=s.blocking;(!O(r)||!i.has(r))&&t.push(h("open_questions",`unknown blocking milestone "${r}"`)),typeof s.surfaced!="boolean"&&t.push(h(`open_questions[${s.id}]`,"surfaced must be boolean",s.surfaced)),typeof s.answered!="boolean"&&t.push(h(`open_questions[${s.id}]`,"answered must be boolean",s.answered))}const a=e.dispatch_units;if(a!==void 0)if(!Array.isArray(a))t.push(h("dispatch_units","must be an array if present",a));else for(const s of a){if(!S(s))continue;const r=s.fits_context_window;typeof r!="boolean"&&t.push(h(`dispatch_units[${s.id}]`,"fits_context_window must be boolean",r));const c=s.milestones;if(Array.isArray(c))for(const u of c)O(u)&&!i.has(u)&&t.push(h(`dispatch_units[${s.id}].milestones`,`unknown milestone "${u}"`))}S(e.pairwise_overlap)||t.push(h("pairwise_overlap","must be an object",e.pairwise_overlap))}return{valid:t.length===0,errors:t}}function he(e){const t=ge(e);if(!t.valid)throw new Error(`Snapshot validation failed:
+${t.errors.map(n=>`  ${n.path}: ${n.message}`).join(`
+`)}`)}const U={prose:5.5,md:5.5,ts:6.3,tsx:6.3,py:6.3,default:4};function N(e,t){if(e<=0)return 0;const o=U[""]??U.default??4;return Math.ceil(e/o)}function Z(e,t){if(e.length===0||t.fileSizes===void 0)return new Map;try{return t.fileSizes(e)}catch{return new Map}}const be={low:600,medium:1e3,high:2e3},ye=de;function ve(e){const t=e.properties??{};return Object.keys(t).length||Object.keys(e).length}function we(e,t){if(e.type==="tool-call")return 0;const n=e.shape;if(!n||n.kind===null)return 0;const o=n.kind;if(o==="function"||o==="interface"||o==="type"||o==="class"||o==="enum"||o==="const"||o==="script")return("ops"in n&&Array.isArray(n.ops)?n.ops:[]).length*200;if(o==="config"||o==="env"||o==="schema"||o==="manifest")return("ops"in n&&Array.isArray(n.ops)?n.ops:[]).length*100;if(o==="doc")return be[t??"medium"]??1e3;if(o==="structured-output"){const i="schema"in n&&n.schema?n.schema:{};return ve(i)*50}return 0}function ke(e,t){const n=new Set([...Object.keys(e),...Object.keys(t)]),o={};for(const i of n){const l=e[i];o[i]=l??t[i]??null}return o}function $e(e,t){const n=new Set([...Object.keys(e),...Object.keys(t)]),o={};for(const i of n){const l=e[i]??t[i];if(l===void 0)throw new TypeError(`Model tier "${i}" not found in dag or deps context_window_per_tier`);o[i]=l}return o}function ee(e){var a;const t=Object.keys(e),n=new Map,o=new Map;for(const s of t)n.has(s)||n.set(s,0),o.has(s)||o.set(s,[]);for(const s of t){const r=((a=e[s])==null?void 0:a.depends_on)??[];for(const c of r){const u=o.get(c);u!==void 0&&u.push(s),n.set(s,(n.get(s)??0)+1)}}const i=new Map,l=[];let f=t.filter(s=>(n.get(s)??0)===0).sort();for(const s of f)i.set(s,0);for(;f.length>0;){const s=[];for(const r of f){l.push(r);const c=(o.get(r)??[]).slice().sort();for(const u of c){const p=(n.get(u)??0)-1;n.set(u,p);const _=i.get(r)??0,b=i.get(u)??0;i.set(u,Math.max(b,_+1)),p===0&&s.push(u)}}f=s.sort()}if(l.length!==t.length){const s=new Set(l),r=t.filter(c=>!s.has(c));throw new Error(`snapshot(): cycle detected in milestone depends_on graph. Nodes involved: [${r.join(", ")}]`)}return{order:l,waves:i}}function te(e,t){if(t.length===0)return[];const n=new Set(t);return e.filter(o=>o.operations.some(i=>n.has(i)))}function ne(e,t){return e.filter(n=>n.operations.includes(t))}function Ae(e,t,n,o,i){const l=`${e}.guard`,f=[...n,l],a=te(o,f);for(const r of a)for(const c of r.results)if(c.op_id===l&&c.guard_result==="pass")return"complete";for(const r of a)for(const c of r.results)if(f.includes(c.op_id)&&c.status==="failed")return"failed";for(const r of a)for(const c of r.results)if(f.includes(c.op_id)&&c.status==="in_progress")return"in_progress";const s=i.length===0||i.every(r=>r==="complete");return t.pending!==null&&s?"pending-surfaced":"pending"}function Oe(e,t){const n=`${e}.guard`;let o=null,i=null,l=null;for(const f of t)if(f.operations.includes(n))for(const a of f.results)a.op_id===n&&a.guard_result!==null&&(o=a.guard_result,i=a.guard_output,a.guard_result==="pass"&&(l=a.guard_ran_at));return o!==null?{guard_result:o,guard_output:i,completed_at:l}:{guard_result:"pending",guard_output:null,completed_at:null}}function Se(e){const t=new Set;for(const n of e)n.action==="move"&&n.to_file?t.add(n.to_file):ye.has(n.action)&&n.file&&t.add(n.file);return Array.from(t)}function Me(e,t,n){const o=ne(n,e.id),i=o.map(c=>c.id);let l=null,f=null,a=null;for(const c of o)for(const u of c.results)u.op_id===e.id&&u.guard_result!==null&&(l=u.guard_result,f=u.guard_output,a=u.guard_ran_at);const s=e.ki_estimate!==null&&e.ki_estimate!==void 0?e.ki_estimate:we(e,t),r=je(e.shape);return{...e,ki_estimate:s,shape:r,dispatch_ids:i,attempt_count:0,guard_result:l,guard_output:f,guard_ran_at:a,blast_radius:[],conflict:{detected:!1,competing_op:null,op_key:null,resolution:null},tokens_actual:null}}function je(e){if(!e)return null;if(e.kind===null)return e;const t=e.kind;if(t==="function"||t==="interface"||t==="type"||t==="class"||t==="enum"||t==="const"||t==="script"||t==="config"||t==="env"||t==="schema"||t==="manifest"){const n=("ops"in e&&Array.isArray(e.ops)?e.ops:[]).map(o=>({...o,from:null,breaking:null,severity:null}));return{...e,ops:n}}return e}function Te(e,t,n,o){const i=`${e}.guard`,l=ne(o,i),f=l.map(c=>c.id);let a=null,s=null,r=null;for(const c of l)for(const u of c.results)u.op_id===i&&u.guard_result!==null&&(a=u.guard_result,s=u.guard_output,r=u.guard_ran_at);return{id:i,milestone:e,depends_on:n,type:"tool-call",action:"guard",file:null,symbol:null,provenance:null,confidence:null,audit_check:null,criteria:[],tool:null,args:null,guard:t.guard??null,to_file:null,to_symbol:null,ki_estimate:0,ki_source:null,authored_by:"synthesized",status:"pending",shape:null,dispatch_ids:f,attempt_count:0,guard_result:a,guard_output:s,guard_ran_at:r,blast_radius:[],conflict:{detected:!1,competing_op:null,op_key:null,resolution:null},tokens_actual:null}}function Ie(e,t){const n={},{write_multiplier:o,read_multiplier:i,hit_probability:l}=t;for(const[f,a]of Object.entries(e))a===null?n[f]=null:n[f]=Math.round(a*((1-l)*o+l*i));return n}function xe(e,t,n){const o=Array.from(e.keys()),i={};for(let l=0;l<o.length;l++)for(let f=l+1;f<o.length;f++){const a=o[l],s=o[f];if(a===void 0||s===void 0)continue;const[r,c]=a<s?[a,s]:[s,a],u=`${r}:${c}`,p=e.get(a)??[],_=e.get(s)??[],b=new Set(p.map(w=>w.file).filter(w=>w!==null)),v=new Set(_.map(w=>w.file).filter(w=>w!==null)),y=Array.from(b).filter(w=>v.has(w));if(y.length===0)continue;const k=t.get(a)??"pending",$=t.get(s)??"pending",M=k==="complete"&&$==="complete";let P=0;for(const w of y)P+=M?n(w):0;i[u]=P}return i}function ze(e){return(Array.isArray(e)?e:Object.values(e)).map(n=>n.type===void 0?{...n,type:"generative"}:n)}function Pe(e,t){const n=new Date().toISOString(),o=t.dispatchLog??e.dispatch_log,i=e.optimization.sentinel_fanout,l=ke(e.optimization.b_per_tier,t.bPerTier),f=$e(e.optimization.context_window_per_tier,t.contextWindowPerTier),a=Ie(l,i),{waves:s}=ee(e.milestones),r=ze(e.operations),c=new Map;for(const m of r){const d=c.get(m.milestone)??[];d.push(m),c.set(m.milestone,d)}const u=new Set;for(const m of r)m.file&&u.add(m.file),m.action==="move"&&m.to_file&&u.add(m.to_file);const p=Z(Array.from(u),t),_=m=>p.get(m)??0,b=new Map,v=Array.from(s.entries()).sort((m,d)=>m[1]-d[1]||m[0].localeCompare(d[0])).map(([m])=>m);for(const m of v){const d=e.milestones[m];if(d===void 0)continue;const j=(c.get(m)??[]).map(I=>I.id),T=d.depends_on.map(I=>b.get(I)??"pending"),x=Ae(m,d,j,o,T);b.set(m,x)}const y={},k=[];for(const m of v){const d=e.milestones[m];if(d===void 0)continue;const j=s.get(m)??0,T=c.get(m)??[],x=T.map(g=>g.id),I=b.get(m)??"pending",D=d.depends_on.map(g=>b.get(g)??"pending"),le=d.depends_on.length===0||D.every(g=>g==="complete"),ue=D.every(g=>g!=="failed"),ae=d.pending===null&&le&&ue,E=te(o,[...x,`${m}.guard`]),ce=E.length>0?E.map(g=>g.started_at).sort()[0]??null:null;let F,q,B;if(d.guard){const g=Oe(m,o);F=g.guard_result,q=g.guard_output,B=g.completed_at}else F=null,q=null,B=null;const R=Se(T),K=R.reduce((g,A)=>g+_(A),0),W=T.map(g=>Me(g,d.effort,o));let z=null,G=0,L=!1;for(const g of W){if(g.ki_estimate===null){L=!0;break}G+=g.ki_estimate}L||(z=G);let V=null;const Y=d.model;if(Y!==null&&z!==null){const g=a[Y]??null;if(g!==null){const A=N(K);V=g+A+z}}let H=null;const J=E.filter(g=>g.completed_at!==null&&g.results.length>0&&g.results.every(A=>A.status==="complete"||A.status==="skipped"));J.length>0&&(H=J.reduce((g,A)=>g+A.turns.reduce((pe,Q)=>pe+Q.input_tokens+Q.output_tokens,0),0));const fe=Te(m,d,x,o);k.push(...W,fe),y[m]={description:d.description,...d.rationale!==void 0?{rationale:d.rationale}:{},authored_by:d.authored_by,pending:d.pending,triggered_by:d.triggered_by,phase:d.phase,depends_on:d.depends_on,agent:d.agent,model:d.model,effort:d.effort,two_stage:d.two_stage,read_only:d.read_only,guard:d.guard,context:`contexts/${m}.md`,wave:j,eligible:ae,status:I,started_at:ce,completed_at:B,guard_result:F,guard_output:q,artifacts:R,si_bytes:K,ki_estimate:z,tokens_estimated:V,tokens_actual:H}}const $=xe(c,b,_),M=Ee(e,y),w={tokens_naive:(()=>{let m=0;for(const d of Object.values(y))if(d.eligible&&d.status==="pending"&&d.model!==null){const j=l[d.model]??t.bPerTier[d.model]??0;m+=j+(d.ki_estimate??0)}return m})(),sentinel_fanout:i,context_window_override:e.optimization.context_window_override,b_override:e.optimization.b_override,b_per_tier:l,b_eff_per_tier:a,context_window_per_tier:f},C={snapshot_at:n,snapshot_version:1,plan:"",schema_version:e.schema_version,plan_kind:e.plan_kind,description:e.description,problem:e.problem,approach:e.approach,executor:e.executor,...e.executor_model!==void 0?{executor_model:e.executor_model}:{},...e.executor_effort!==void 0?{executor_effort:e.executor_effort}:{},phases:[...e.phases],terminal:e.terminal,...e.assumed_baseline!==void 0?{assumed_baseline:e.assumed_baseline}:{},optimization:w,milestones:y,operations:k,pairwise_overlap:$,open_questions:M};return he(C),C}function Ee(e,t){const n=[];for(const[o,i]of Object.entries(t)){const l=e.milestones[o];if(l===void 0||l.pending===null)continue;const f=i.status==="pending-surfaced";n.push({id:`q:${o}`,text:l.pending,blocking:o,surfaced:f,raised_at_dispatch:null,raised_at_turn:null,answered:!1,answer:null})}return n}function oe(e){return Object.keys(e.milestones).filter(t=>{const n=e.milestones[t];return n!==void 0&&n.eligible===!0&&n.status==="pending"})}function Fe(e){if(e.length===0||e.every(t=>t.type==="tool-call"))return"tool-call";for(const t of e){if(t.type!=="generative"||!t.shape||t.shape.kind===null)continue;const n=t.shape.kind;if(n==="function"||n==="interface"||n==="type"||n==="class"||n==="enum"||n==="const"||n==="script"||n==="config"||n==="env"||n==="schema"||n==="manifest")return"code-config";if(n==="doc")return"doc";if(n==="structured-output")return"structured"}return"code-config"}function qe(e){if(!e)return"";const t=e.indexOf(":");return t>=0?e.slice(t+1):e}function Be(e,t,n){let o=!0;const i=[];for(const l of e){const f=t[l];if(f===void 0)continue;const a=n.filter(r=>r.milestone===l&&r.action!=="guard");a.some(r=>r.type==="generative")&&(o=!1),i.push(`## Milestone: ${l}`),i.push(f.description),f.rationale&&i.push(`
+*Rationale:* ${f.rationale}`),i.push(`
+### Operations:`);for(const r of a){const c=r.file?` ${r.file}`:"",u=r.symbol?` (${r.symbol})`:"";if(i.push(`- [${r.id}] ${r.action}${c}${u}`),r.shape&&r.shape.kind!==null){const p=r.shape;if(p.kind==="doc")i.push(`  Description: ${p.description}`),i.push(`  Objective: ${p.objective}`),p.required_sections&&p.required_sections.length>0&&i.push(`  Required sections: ${p.required_sections.join(", ")}`);else if(p.kind==="structured-output")i.push(`  Schema:
+`+JSON.stringify(p.schema,null,2).split(`
+`).map(_=>`    ${_}`).join(`
+`));else if("ops"in p&&Array.isArray(p.ops))for(const _ of p.ops){const b=_.to!==null?` → ${_.to}`:"",v=_.target!==null?` "${_.target}"`:"";i.push(`    - ${_.op}${v}${b}`)}}}const s=f.guard;i.push(`
+### Guard: ${s??"none"}`),i.push("")}return o?null:i.join(`
+`)}function se(e,t,n){if(e===null)return null;const o=t.optimization.b_eff_per_tier[e];if(o!=null)return o;const i=t.optimization.b_per_tier[e];if(i!=null)return i;const l=n.bPerTier[e];return l!==void 0?l:null}function ie(e,t,n){if(e===null)return Number.POSITIVE_INFINITY;const o=t.optimization.context_window_per_tier[e];if(o!==void 0)return o;const i=n.contextWindowPerTier[e];return i!==void 0?i:Number.POSITIVE_INFINITY}function re(e,t){const n=new Set;for(const o of e){const i=t.snapshot.milestones[o];if(i!==void 0){n.add(i.context);for(const l of i.read_only)n.add(l);for(const l of t.opsByMilestone.get(o)??[])l.file&&n.add(l.file)}}return Array.from(n)}function X(e,t,n){const o=se(t,n.snapshot,n.deps);if(o===null)return null;const l=re(e,n).reduce((s,r)=>s+(n.sizeMap.get(r)??0),0),f=N(l),a=e.reduce((s,r)=>{var c;return s+(((c=n.snapshot.milestones[r])==null?void 0:c.ki_estimate)??0)},0);return o+f+a}function Ne(e,t,n){const o=ie(t,n.snapshot,n.deps),i=[...e].sort((a,s)=>{var u,p;const r=((u=n.snapshot.milestones[a])==null?void 0:u.ki_estimate)??0,c=((p=n.snapshot.milestones[s])==null?void 0:p.ki_estimate)??0;return r-c||a.localeCompare(s)}),l=[];let f=[];for(const a of i){const s=[...f,a],r=X(s,t,n);r!==null&&r>o&&f.length>0?(l.push(f),f=[a]):f=s}return f.length>0&&l.push(f),l.filter(a=>{const s=X(a,t,n);return s===null||s<=o})}function Ce(e,t,n,o){const i=e[0]??"",l=o.snapshot.milestones[i],f=(l==null?void 0:l.effort)??null,a=[];for(const k of e)for(const $ of o.opsByMilestone.get(k)??[])a.push($.id);const s=re(e,o),r=s.reduce((k,$)=>k+(o.sizeMap.get($)??0),0),c=se(n,o.snapshot,o.deps),u=e.reduce((k,$)=>{var M;return k+(((M=o.snapshot.milestones[$])==null?void 0:M.ki_estimate)??0)},0),p=c!==null?c+N(r)+u:null,_=ie(n,o.snapshot,o.deps),b=p!==null?p<=_:!0,v=qe((l==null?void 0:l.agent)??null),y=Be(e,o.snapshot.milestones,o.snapshot.operations);return{id:`${i}.dispatch.${t}`,milestones:e,operations:a,model:n,effort:f,two_stage:(l==null?void 0:l.two_stage)??!1,provider:null,agent_name:v,mcp_servers:null,resolved_max_tokens:null,background:!0,prompt:y,context_files:s,si_bytes:r,tokens_estimated:p,fits_context_window:b,sentinel_role:null,dispatch_log_id:null,remote_task_id:null,result:null,status:"pending",started_at:null,completed_at:null,tokens_actual:null}}function De(e,t){const n=oe(e);if(n.length===0)return[];const o=new Map;for(const u of e.operations){if(u.action==="guard")continue;const p=o.get(u.milestone)??[];p.push(u),o.set(u.milestone,p)}const i=new Map;for(const u of n){const p=e.milestones[u];if(p===void 0)continue;const _=Fe(o.get(u)??[]),b=p.model??"_null",v=`${_}:${b}`,y=i.get(v)??[];y.push(u),i.set(v,y)}const l=new Set;for(const u of n){const p=e.milestones[u];if(p!==void 0){l.add(p.context);for(const _ of p.read_only)l.add(_);for(const _ of o.get(u)??[])_.file&&l.add(_.file)}}const f=Z(Array.from(l),t),a={snapshot:e,deps:t,sizeMap:f,opsByMilestone:o},s=[];let r=0;const c=Array.from(i.keys()).sort();for(const u of c){const p=i.get(u);if(p===void 0)continue;const _=u.slice(u.indexOf(":")+1),b=_!=="_null"?_:null,v=Ne(p,b,a);for(const y of v)s.push(Ce(y,r++,b,a))}return s}function Re(e,t){let n=0;for(const o of oe(e)){const i=e.milestones[o];if(i===void 0)continue;const l=Ke(i.model,e,t)??0;n+=l+(i.ki_estimate??0)}return n}function Ke(e,t,n){if(e===null)return null;const o=t.optimization.b_per_tier[e];if(o!=null)return o;const i=n.bPerTier[e];return i!==void 0?i:null}exports.computeTokensNaive=Re;exports.optimize=De;exports.snapshot=Pe;exports.topoSortMilestones=ee;

package/index.mjs

@@ -0,0 +1,901 @@
+const pe = /* @__PURE__ */ new Set([
+  "create",
+  "modify-signature",
+  "modify-body",
+  "add-export",
+  "remove-export",
+  "rename"
+]), de = /* @__PURE__ */ new Set([
+  "pending",
+  "pending-surfaced",
+  "in_progress",
+  "complete",
+  "failed",
+  "skipped"
+]), _e = /* @__PURE__ */ new Set([
+  "pending",
+  "in_progress",
+  "complete",
+  "failed",
+  "skipped"
+]);
+function S(e) {
+  return typeof e == "object" && e !== null && !Array.isArray(e);
+}
+function O(e) {
+  return typeof e == "string";
+}
+function g(e, t, n) {
+  return { path: e, message: t, value: n };
+}
+function me(e) {
+  const t = [];
+  if (!S(e))
+    return { valid: !1, errors: [g("", "root must be an object")] };
+  for (const o of ["snapshot_at", "description"])
+    O(e[o]) || t.push(g(o, "required string field missing", e[o]));
+  O(e.plan) || t.push(g("plan", "required string", e.plan));
+  const n = e.milestones;
+  if (!S(n))
+    t.push(g("milestones", "must be an object", n));
+  else {
+    const o = Object.keys(n), i = new Set(o);
+    for (const s of o) {
+      const r = n[s];
+      if (!S(r)) {
+        t.push(g(`milestones.${s}`, "must be an object", r));
+        continue;
+      }
+      const c = r.eligible, u = r.pending;
+      c === !0 && u !== null && u !== void 0 && t.push(
+        g(
+          `milestones.${s}`,
+          "D-07 violation: eligible=true but pending not null"
+        )
+      ), typeof c != "boolean" && t.push(
+        g(`milestones.${s}.eligible`, "must be boolean", c)
+      );
+      const p = r.status;
+      (!O(p) || !de.has(p)) && t.push(g(`milestones.${s}.status`, "invalid status", p));
+      const m = r.wave;
+      (typeof m != "number" || !Number.isInteger(m) || m < 0) && t.push(
+        g(`milestones.${s}.wave`, "must be non-negative integer", m)
+      );
+      const b = r.ki_estimate;
+      b != null && typeof b != "number" && t.push(
+        g(`milestones.${s}.ki_estimate`, "must be number|null", b)
+      );
+      for (const v of ["tokens_estimated", "tokens_actual"]) {
+        const y = r[v];
+        y != null && typeof y != "number" && t.push(g(`milestones.${s}.${v}`, "must be number|null", y));
+      }
+      Array.isArray(r.artifacts) || t.push(
+        g(
+          `milestones.${s}.artifacts`,
+          "must be an array",
+          r.artifacts
+        )
+      ), typeof r.si_bytes != "number" && t.push(
+        g(`milestones.${s}.si_bytes`, "must be a number", r.si_bytes)
+      );
+    }
+    const l = e.operations;
+    if (!Array.isArray(l))
+      t.push(g("operations", "must be an array", l));
+    else
+      for (const s of l) {
+        if (!S(s))
+          continue;
+        const r = O(s.id) ? s.id : "?", c = s.milestone;
+        O(c) && !i.has(c) && t.push(
+          g(
+            `operations[${r}].milestone`,
+            `unknown milestone "${c}"`
+          )
+        );
+        const u = s.status;
+        (!O(u) || !_e.has(u)) && t.push(
+          g(
+            `operations[${r}].status`,
+            "invalid operation status",
+            u
+          )
+        ), Array.isArray(s.dispatch_ids) || t.push(
+          g(
+            `operations[${r}].dispatch_ids`,
+            "must be an array",
+            s.dispatch_ids
+          )
+        ), typeof s.attempt_count != "number" && t.push(
+          g(
+            `operations[${r}].attempt_count`,
+            "must be a number",
+            s.attempt_count
+          )
+        ), Array.isArray(s.blast_radius) || t.push(
+          g(
+            `operations[${r}].blast_radius`,
+            "must be an array",
+            s.blast_radius
+          )
+        );
+      }
+    const f = e.open_questions;
+    if (!Array.isArray(f))
+      t.push(g("open_questions", "must be an array", f));
+    else
+      for (const s of f) {
+        if (!S(s))
+          continue;
+        const r = s.blocking;
+        (!O(r) || !i.has(r)) && t.push(
+          g("open_questions", `unknown blocking milestone "${r}"`)
+        ), typeof s.surfaced != "boolean" && t.push(
+          g(
+            `open_questions[${s.id}]`,
+            "surfaced must be boolean",
+            s.surfaced
+          )
+        ), typeof s.answered != "boolean" && t.push(
+          g(
+            `open_questions[${s.id}]`,
+            "answered must be boolean",
+            s.answered
+          )
+        );
+      }
+    const a = e.dispatch_units;
+    if (a !== void 0)
+      if (!Array.isArray(a))
+        t.push(
+          g("dispatch_units", "must be an array if present", a)
+        );
+      else
+        for (const s of a) {
+          if (!S(s))
+            continue;
+          const r = s.fits_context_window;
+          typeof r != "boolean" && t.push(
+            g(
+              `dispatch_units[${s.id}]`,
+              "fits_context_window must be boolean",
+              r
+            )
+          );
+          const c = s.milestones;
+          if (Array.isArray(c))
+            for (const u of c)
+              O(u) && !i.has(u) && t.push(
+                g(
+                  `dispatch_units[${s.id}].milestones`,
+                  `unknown milestone "${u}"`
+                )
+              );
+        }
+    S(e.pairwise_overlap) || t.push(
+      g(
+        "pairwise_overlap",
+        "must be an object",
+        e.pairwise_overlap
+      )
+    );
+  }
+  return { valid: t.length === 0, errors: t };
+}
+function he(e) {
+  const t = me(e);
+  if (!t.valid)
+    throw new Error(
+      `Snapshot validation failed:
+${t.errors.map((n) => `  ${n.path}: ${n.message}`).join(`
+`)}`
+    );
+}
+const U = {
+  prose: 5.5,
+  md: 5.5,
+  ts: 6.3,
+  tsx: 6.3,
+  py: 6.3,
+  default: 4
+};
+function C(e, t) {
+  if (e <= 0)
+    return 0;
+  const o = U[""] ?? U.default ?? 4;
+  return Math.ceil(e / o);
+}
+function Z(e, t) {
+  if (e.length === 0 || t.fileSizes === void 0)
+    return /* @__PURE__ */ new Map();
+  try {
+    return t.fileSizes(e);
+  } catch {
+    return /* @__PURE__ */ new Map();
+  }
+}
+const ge = {
+  low: 600,
+  medium: 1e3,
+  high: 2e3
+}, be = pe;
+function ye(e) {
+  const t = e.properties ?? {};
+  return Object.keys(t).length || Object.keys(e).length;
+}
+function ve(e, t) {
+  if (e.type === "tool-call")
+    return 0;
+  const n = e.shape;
+  if (!n || n.kind === null)
+    return 0;
+  const o = n.kind;
+  if (o === "function" || o === "interface" || o === "type" || o === "class" || o === "enum" || o === "const" || o === "script")
+    return ("ops" in n && Array.isArray(n.ops) ? n.ops : []).length * 200;
+  if (o === "config" || o === "env" || o === "schema" || o === "manifest")
+    return ("ops" in n && Array.isArray(n.ops) ? n.ops : []).length * 100;
+  if (o === "doc")
+    return ge[t ?? "medium"] ?? 1e3;
+  if (o === "structured-output") {
+    const i = "schema" in n && n.schema ? n.schema : {};
+    return ye(i) * 50;
+  }
+  return 0;
+}
+function we(e, t) {
+  const n = /* @__PURE__ */ new Set([...Object.keys(e), ...Object.keys(t)]), o = {};
+  for (const i of n) {
+    const l = e[i];
+    o[i] = l ?? t[i] ?? null;
+  }
+  return o;
+}
+function ke(e, t) {
+  const n = /* @__PURE__ */ new Set([...Object.keys(e), ...Object.keys(t)]), o = {};
+  for (const i of n) {
+    const l = e[i] ?? t[i];
+    if (l === void 0)
+      throw new TypeError(
+        `Model tier "${i}" not found in dag or deps context_window_per_tier`
+      );
+    o[i] = l;
+  }
+  return o;
+}
+function $e(e) {
+  var a;
+  const t = Object.keys(e), n = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Map();
+  for (const s of t)
+    n.has(s) || n.set(s, 0), o.has(s) || o.set(s, []);
+  for (const s of t) {
+    const r = ((a = e[s]) == null ? void 0 : a.depends_on) ?? [];
+    for (const c of r) {
+      const u = o.get(c);
+      u !== void 0 && u.push(s), n.set(s, (n.get(s) ?? 0) + 1);
+    }
+  }
+  const i = /* @__PURE__ */ new Map(), l = [];
+  let f = t.filter((s) => (n.get(s) ?? 0) === 0).sort();
+  for (const s of f)
+    i.set(s, 0);
+  for (; f.length > 0; ) {
+    const s = [];
+    for (const r of f) {
+      l.push(r);
+      const c = (o.get(r) ?? []).slice().sort();
+      for (const u of c) {
+        const p = (n.get(u) ?? 0) - 1;
+        n.set(u, p);
+        const m = i.get(r) ?? 0, b = i.get(u) ?? 0;
+        i.set(u, Math.max(b, m + 1)), p === 0 && s.push(u);
+      }
+    }
+    f = s.sort();
+  }
+  if (l.length !== t.length) {
+    const s = new Set(l), r = t.filter((c) => !s.has(c));
+    throw new Error(
+      `snapshot(): cycle detected in milestone depends_on graph. Nodes involved: [${r.join(", ")}]`
+    );
+  }
+  return { order: l, waves: i };
+}
+function ee(e, t) {
+  if (t.length === 0)
+    return [];
+  const n = new Set(t);
+  return e.filter(
+    (o) => o.operations.some((i) => n.has(i))
+  );
+}
+function te(e, t) {
+  return e.filter((n) => n.operations.includes(t));
+}
+function Ae(e, t, n, o, i) {
+  const l = `${e}.guard`, f = [...n, l], a = ee(o, f);
+  for (const r of a)
+    for (const c of r.results)
+      if (c.op_id === l && c.guard_result === "pass")
+        return "complete";
+  for (const r of a)
+    for (const c of r.results)
+      if (f.includes(c.op_id) && c.status === "failed")
+        return "failed";
+  for (const r of a)
+    for (const c of r.results)
+      if (f.includes(c.op_id) && // "in_progress" is not a dispatch_log result status (only complete/failed/skipped)
+      // but orchestrators may write it; guard defensively
+      c.status === "in_progress")
+        return "in_progress";
+  const s = i.length === 0 || i.every((r) => r === "complete");
+  return t.pending !== null && s ? "pending-surfaced" : "pending";
+}
+function Oe(e, t) {
+  const n = `${e}.guard`;
+  let o = null, i = null, l = null;
+  for (const f of t)
+    if (f.operations.includes(n))
+      for (const a of f.results)
+        a.op_id === n && a.guard_result !== null && (o = a.guard_result, i = a.guard_output, a.guard_result === "pass" && (l = a.guard_ran_at));
+  return o !== null ? {
+    guard_result: o,
+    guard_output: i,
+    completed_at: l
+  } : { guard_result: "pending", guard_output: null, completed_at: null };
+}
+function Se(e) {
+  const t = /* @__PURE__ */ new Set();
+  for (const n of e)
+    n.action === "move" && n.to_file ? t.add(n.to_file) : be.has(n.action) && n.file && t.add(n.file);
+  return Array.from(t);
+}
+function je(e, t, n) {
+  const o = te(n, e.id), i = o.map((c) => c.id);
+  let l = null, f = null, a = null;
+  for (const c of o)
+    for (const u of c.results)
+      u.op_id === e.id && u.guard_result !== null && (l = u.guard_result, f = u.guard_output, a = u.guard_ran_at);
+  const s = e.ki_estimate !== null && e.ki_estimate !== void 0 ? e.ki_estimate : ve(e, t), r = Me(e.shape);
+  return {
+    ...e,
+    ki_estimate: s,
+    shape: r,
+    dispatch_ids: i,
+    // TODO: stubbed as 0 — op-level attempt_count requires per-op dispatch log scan
+    attempt_count: 0,
+    guard_result: l,
+    guard_output: f,
+    guard_ran_at: a,
+    // TODO: stubbed — requires gitnexus_impact MCP call (future work)
+    blast_radius: [],
+    // TODO: stubbed — requires same-wave op-key collision scan (future work)
+    conflict: {
+      detected: !1,
+      competing_op: null,
+      op_key: null,
+      resolution: null
+    },
+    // TODO: stubbed — requires ki_estimate share prorating across dispatch totals
+    tokens_actual: null
+  };
+}
+function Me(e) {
+  if (!e)
+    return null;
+  if (e.kind === null)
+    return e;
+  const t = e.kind;
+  if (t === "function" || t === "interface" || t === "type" || t === "class" || t === "enum" || t === "const" || t === "script" || t === "config" || t === "env" || t === "schema" || t === "manifest") {
+    const n = ("ops" in e && Array.isArray(e.ops) ? e.ops : []).map((o) => ({
+      ...o,
+      // TODO: from/breaking/severity require AST read + gitnexus (future work)
+      from: null,
+      breaking: null,
+      severity: null
+    }));
+    return { ...e, ops: n };
+  }
+  return e;
+}
+function Te(e, t, n, o) {
+  const i = `${e}.guard`, l = te(o, i), f = l.map((c) => c.id);
+  let a = null, s = null, r = null;
+  for (const c of l)
+    for (const u of c.results)
+      u.op_id === i && u.guard_result !== null && (a = u.guard_result, s = u.guard_output, r = u.guard_ran_at);
+  return {
+    id: i,
+    milestone: e,
+    depends_on: n,
+    type: "tool-call",
+    action: "guard",
+    file: null,
+    symbol: null,
+    provenance: null,
+    confidence: null,
+    audit_check: null,
+    criteria: [],
+    tool: null,
+    args: null,
+    guard: t.guard ?? null,
+    to_file: null,
+    to_symbol: null,
+    ki_estimate: 0,
+    ki_source: null,
+    authored_by: "synthesized",
+    status: "pending",
+    shape: null,
+    dispatch_ids: f,
+    attempt_count: 0,
+    guard_result: a,
+    guard_output: s,
+    guard_ran_at: r,
+    blast_radius: [],
+    conflict: {
+      detected: !1,
+      competing_op: null,
+      op_key: null,
+      resolution: null
+    },
+    tokens_actual: null
+  };
+}
+function xe(e, t) {
+  const n = {}, {
+    write_multiplier: o,
+    read_multiplier: i,
+    hit_probability: l
+  } = t;
+  for (const [f, a] of Object.entries(e))
+    a === null ? n[f] = null : n[f] = Math.round(a * ((1 - l) * o + l * i));
+  return n;
+}
+function Ie(e, t, n) {
+  const o = Array.from(e.keys()), i = {};
+  for (let l = 0; l < o.length; l++)
+    for (let f = l + 1; f < o.length; f++) {
+      const a = o[l], s = o[f];
+      if (a === void 0 || s === void 0)
+        continue;
+      const [r, c] = a < s ? [a, s] : [s, a], u = `${r}:${c}`, p = e.get(a) ?? [], m = e.get(s) ?? [], b = new Set(
+        p.map((w) => w.file).filter((w) => w !== null)
+      ), v = new Set(
+        m.map((w) => w.file).filter((w) => w !== null)
+      ), y = Array.from(b).filter((w) => v.has(w));
+      if (y.length === 0)
+        continue;
+      const k = t.get(a) ?? "pending", $ = t.get(s) ?? "pending", j = k === "complete" && $ === "complete";
+      let P = 0;
+      for (const w of y)
+        P += j ? n(w) : 0;
+      i[u] = P;
+    }
+  return i;
+}
+function ze(e) {
+  return (Array.isArray(e) ? e : Object.values(e)).map(
+    (n) => n.type === void 0 ? { ...n, type: "generative" } : n
+  );
+}
+function Ne(e, t) {
+  const n = (/* @__PURE__ */ new Date()).toISOString(), o = t.dispatchLog ?? e.dispatch_log, i = e.optimization.sentinel_fanout, l = we(e.optimization.b_per_tier, t.bPerTier), f = ke(
+    e.optimization.context_window_per_tier,
+    t.contextWindowPerTier
+  ), a = xe(l, i), { waves: s } = $e(e.milestones), r = ze(e.operations), c = /* @__PURE__ */ new Map();
+  for (const _ of r) {
+    const d = c.get(_.milestone) ?? [];
+    d.push(_), c.set(_.milestone, d);
+  }
+  const u = /* @__PURE__ */ new Set();
+  for (const _ of r)
+    _.file && u.add(_.file), _.action === "move" && _.to_file && u.add(_.to_file);
+  const p = Z(Array.from(u), t), m = (_) => p.get(_) ?? 0, b = /* @__PURE__ */ new Map(), v = Array.from(s.entries()).sort((_, d) => _[1] - d[1] || _[0].localeCompare(d[0])).map(([_]) => _);
+  for (const _ of v) {
+    const d = e.milestones[_];
+    if (d === void 0)
+      continue;
+    const M = (c.get(_) ?? []).map((x) => x.id), T = d.depends_on.map(
+      (x) => b.get(x) ?? "pending"
+    ), I = Ae(
+      _,
+      d,
+      M,
+      o,
+      T
+    );
+    b.set(_, I);
+  }
+  const y = {}, k = [];
+  for (const _ of v) {
+    const d = e.milestones[_];
+    if (d === void 0)
+      continue;
+    const M = s.get(_) ?? 0, T = c.get(_) ?? [], I = T.map((h) => h.id), x = b.get(_) ?? "pending", N = d.depends_on.map(
+      (h) => b.get(h) ?? "pending"
+    ), re = d.depends_on.length === 0 || N.every((h) => h === "complete"), le = N.every((h) => h !== "failed"), ue = d.pending === null && re && le, E = ee(o, [
+      ...I,
+      `${_}.guard`
+    ]), ae = E.length > 0 ? E.map((h) => h.started_at).sort()[0] ?? null : null;
+    let F, q, B;
+    if (d.guard) {
+      const h = Oe(_, o);
+      F = h.guard_result, q = h.guard_output, B = h.completed_at;
+    } else
+      F = null, q = null, B = null;
+    const R = Se(T), K = R.reduce((h, A) => h + m(A), 0), W = T.map(
+      (h) => je(h, d.effort, o)
+    );
+    let z = null, G = 0, L = !1;
+    for (const h of W) {
+      if (h.ki_estimate === null) {
+        L = !0;
+        break;
+      }
+      G += h.ki_estimate;
+    }
+    L || (z = G);
+    let V = null;
+    const Y = d.model;
+    if (Y !== null && z !== null) {
+      const h = a[Y] ?? null;
+      if (h !== null) {
+        const A = C(K);
+        V = h + A + z;
+      }
+    }
+    let H = null;
+    const J = E.filter(
+      (h) => h.completed_at !== null && h.results.length > 0 && h.results.every(
+        (A) => A.status === "complete" || A.status === "skipped"
+      )
+    );
+    J.length > 0 && (H = J.reduce((h, A) => h + A.turns.reduce((fe, Q) => fe + Q.input_tokens + Q.output_tokens, 0), 0));
+    const ce = Te(
+      _,
+      d,
+      I,
+      o
+    );
+    k.push(...W, ce), y[_] = {
+      description: d.description,
+      ...d.rationale !== void 0 ? { rationale: d.rationale } : {},
+      authored_by: d.authored_by,
+      pending: d.pending,
+      triggered_by: d.triggered_by,
+      phase: d.phase,
+      depends_on: d.depends_on,
+      agent: d.agent,
+      model: d.model,
+      effort: d.effort,
+      two_stage: d.two_stage,
+      read_only: d.read_only,
+      guard: d.guard,
+      context: `contexts/${_}.md`,
+      wave: M,
+      eligible: ue,
+      status: x,
+      started_at: ae,
+      completed_at: B,
+      guard_result: F,
+      guard_output: q,
+      artifacts: R,
+      si_bytes: K,
+      ki_estimate: z,
+      tokens_estimated: V,
+      tokens_actual: H
+    };
+  }
+  const $ = Ie(
+    c,
+    b,
+    m
+  ), j = Pe(e, y), w = {
+    tokens_naive: (() => {
+      let _ = 0;
+      for (const d of Object.values(y))
+        if (d.eligible && d.status === "pending" && d.model !== null) {
+          const M = l[d.model] ?? t.bPerTier[d.model] ?? 0;
+          _ += M + (d.ki_estimate ?? 0);
+        }
+      return _;
+    })(),
+    sentinel_fanout: i,
+    context_window_override: e.optimization.context_window_override,
+    b_override: e.optimization.b_override,
+    b_per_tier: l,
+    b_eff_per_tier: a,
+    context_window_per_tier: f
+  }, D = {
+    snapshot_at: n,
+    snapshot_version: 1,
+    // callers may increment if persisting
+    plan: "",
+    // caller sets this from directory name
+    schema_version: e.schema_version,
+    plan_kind: e.plan_kind,
+    description: e.description,
+    problem: e.problem,
+    approach: e.approach,
+    executor: e.executor,
+    ...e.executor_model !== void 0 ? { executor_model: e.executor_model } : {},
+    ...e.executor_effort !== void 0 ? { executor_effort: e.executor_effort } : {},
+    phases: [...e.phases],
+    terminal: e.terminal,
+    ...e.assumed_baseline !== void 0 ? { assumed_baseline: e.assumed_baseline } : {},
+    optimization: w,
+    milestones: y,
+    operations: k,
+    pairwise_overlap: $,
+    open_questions: j
+  };
+  return he(D), D;
+}
+function Pe(e, t) {
+  const n = [];
+  for (const [o, i] of Object.entries(t)) {
+    const l = e.milestones[o];
+    if (l === void 0 || l.pending === null)
+      continue;
+    const f = i.status === "pending-surfaced";
+    n.push({
+      id: `q:${o}`,
+      text: l.pending,
+      blocking: o,
+      surfaced: f,
+      // TODO: scan dispatch_log notes for the turn/dispatch where question appeared
+      raised_at_dispatch: null,
+      raised_at_turn: null,
+      answered: !1,
+      answer: null
+    });
+  }
+  return n;
+}
+function ne(e) {
+  return Object.keys(e.milestones).filter((t) => {
+    const n = e.milestones[t];
+    return n !== void 0 && n.eligible === !0 && n.status === "pending";
+  });
+}
+function Ee(e) {
+  if (e.length === 0 || e.every((t) => t.type === "tool-call"))
+    return "tool-call";
+  for (const t of e) {
+    if (t.type !== "generative" || !t.shape || t.shape.kind === null)
+      continue;
+    const n = t.shape.kind;
+    if (n === "function" || n === "interface" || n === "type" || n === "class" || n === "enum" || n === "const" || n === "script" || n === "config" || n === "env" || n === "schema" || n === "manifest")
+      return "code-config";
+    if (n === "doc")
+      return "doc";
+    if (n === "structured-output")
+      return "structured";
+  }
+  return "code-config";
+}
+function Fe(e) {
+  if (!e)
+    return "";
+  const t = e.indexOf(":");
+  return t >= 0 ? e.slice(t + 1) : e;
+}
+function qe(e, t, n) {
+  let o = !0;
+  const i = [];
+  for (const l of e) {
+    const f = t[l];
+    if (f === void 0)
+      continue;
+    const a = n.filter(
+      (r) => r.milestone === l && r.action !== "guard"
+    );
+    a.some((r) => r.type === "generative") && (o = !1), i.push(`## Milestone: ${l}`), i.push(f.description), f.rationale && i.push(`
+*Rationale:* ${f.rationale}`), i.push(`
+### Operations:`);
+    for (const r of a) {
+      const c = r.file ? ` ${r.file}` : "", u = r.symbol ? ` (${r.symbol})` : "";
+      if (i.push(`- [${r.id}] ${r.action}${c}${u}`), r.shape && r.shape.kind !== null) {
+        const p = r.shape;
+        if (p.kind === "doc")
+          i.push(`  Description: ${p.description}`), i.push(`  Objective: ${p.objective}`), p.required_sections && p.required_sections.length > 0 && i.push(
+            `  Required sections: ${p.required_sections.join(", ")}`
+          );
+        else if (p.kind === "structured-output")
+          i.push(
+            `  Schema:
+` + JSON.stringify(p.schema, null, 2).split(`
+`).map((m) => `    ${m}`).join(`
+`)
+          );
+        else if ("ops" in p && Array.isArray(p.ops))
+          for (const m of p.ops) {
+            const b = m.to !== null ? ` → ${m.to}` : "", v = m.target !== null ? ` "${m.target}"` : "";
+            i.push(`    - ${m.op}${v}${b}`);
+          }
+      }
+    }
+    const s = f.guard;
+    i.push(`
+### Guard: ${s ?? "none"}`), i.push("");
+  }
+  return o ? null : i.join(`
+`);
+}
+function oe(e, t, n) {
+  if (e === null)
+    return null;
+  const o = t.optimization.b_eff_per_tier[e];
+  if (o != null)
+    return o;
+  const i = t.optimization.b_per_tier[e];
+  if (i != null)
+    return i;
+  const l = n.bPerTier[e];
+  return l !== void 0 ? l : null;
+}
+function se(e, t, n) {
+  if (e === null)
+    return Number.POSITIVE_INFINITY;
+  const o = t.optimization.context_window_per_tier[e];
+  if (o !== void 0)
+    return o;
+  const i = n.contextWindowPerTier[e];
+  return i !== void 0 ? i : Number.POSITIVE_INFINITY;
+}
+function ie(e, t) {
+  const n = /* @__PURE__ */ new Set();
+  for (const o of e) {
+    const i = t.snapshot.milestones[o];
+    if (i !== void 0) {
+      n.add(i.context);
+      for (const l of i.read_only)
+        n.add(l);
+      for (const l of t.opsByMilestone.get(o) ?? [])
+        l.file && n.add(l.file);
+    }
+  }
+  return Array.from(n);
+}
+function X(e, t, n) {
+  const o = oe(t, n.snapshot, n.deps);
+  if (o === null)
+    return null;
+  const l = ie(e, n).reduce(
+    (s, r) => s + (n.sizeMap.get(r) ?? 0),
+    0
+  ), f = C(l), a = e.reduce(
+    (s, r) => {
+      var c;
+      return s + (((c = n.snapshot.milestones[r]) == null ? void 0 : c.ki_estimate) ?? 0);
+    },
+    0
+  );
+  return o + f + a;
+}
+function Be(e, t, n) {
+  const o = se(t, n.snapshot, n.deps), i = [...e].sort((a, s) => {
+    var u, p;
+    const r = ((u = n.snapshot.milestones[a]) == null ? void 0 : u.ki_estimate) ?? 0, c = ((p = n.snapshot.milestones[s]) == null ? void 0 : p.ki_estimate) ?? 0;
+    return r - c || a.localeCompare(s);
+  }), l = [];
+  let f = [];
+  for (const a of i) {
+    const s = [...f, a], r = X(s, t, n);
+    r !== null && r > o && f.length > 0 ? (l.push(f), f = [a]) : f = s;
+  }
+  return f.length > 0 && l.push(f), l.filter((a) => {
+    const s = X(a, t, n);
+    return s === null || s <= o;
+  });
+}
+function Ce(e, t, n, o) {
+  const i = e[0] ?? "", l = o.snapshot.milestones[i], f = (l == null ? void 0 : l.effort) ?? null, a = [];
+  for (const k of e)
+    for (const $ of o.opsByMilestone.get(k) ?? [])
+      a.push($.id);
+  const s = ie(e, o), r = s.reduce(
+    (k, $) => k + (o.sizeMap.get($) ?? 0),
+    0
+  ), c = oe(n, o.snapshot, o.deps), u = e.reduce(
+    (k, $) => {
+      var j;
+      return k + (((j = o.snapshot.milestones[$]) == null ? void 0 : j.ki_estimate) ?? 0);
+    },
+    0
+  ), p = c !== null ? c + C(r) + u : null, m = se(n, o.snapshot, o.deps), b = p !== null ? p <= m : !0, v = Fe((l == null ? void 0 : l.agent) ?? null), y = qe(e, o.snapshot.milestones, o.snapshot.operations);
+  return {
+    id: `${i}.dispatch.${t}`,
+    milestones: e,
+    operations: a,
+    model: n,
+    effort: f,
+    two_stage: (l == null ? void 0 : l.two_stage) ?? !1,
+    provider: null,
+    agent_name: v,
+    mcp_servers: null,
+    resolved_max_tokens: null,
+    background: !0,
+    prompt: y,
+    context_files: s,
+    si_bytes: r,
+    tokens_estimated: p,
+    fits_context_window: b,
+    sentinel_role: null,
+    dispatch_log_id: null,
+    remote_task_id: null,
+    result: null,
+    status: "pending",
+    started_at: null,
+    completed_at: null,
+    tokens_actual: null
+  };
+}
+function Re(e, t) {
+  const n = ne(e);
+  if (n.length === 0)
+    return [];
+  const o = /* @__PURE__ */ new Map();
+  for (const u of e.operations) {
+    if (u.action === "guard")
+      continue;
+    const p = o.get(u.milestone) ?? [];
+    p.push(u), o.set(u.milestone, p);
+  }
+  const i = /* @__PURE__ */ new Map();
+  for (const u of n) {
+    const p = e.milestones[u];
+    if (p === void 0)
+      continue;
+    const m = Ee(o.get(u) ?? []), b = p.model ?? "_null", v = `${m}:${b}`, y = i.get(v) ?? [];
+    y.push(u), i.set(v, y);
+  }
+  const l = /* @__PURE__ */ new Set();
+  for (const u of n) {
+    const p = e.milestones[u];
+    if (p !== void 0) {
+      l.add(p.context);
+      for (const m of p.read_only)
+        l.add(m);
+      for (const m of o.get(u) ?? [])
+        m.file && l.add(m.file);
+    }
+  }
+  const f = Z(Array.from(l), t), a = { snapshot: e, deps: t, sizeMap: f, opsByMilestone: o }, s = [];
+  let r = 0;
+  const c = Array.from(i.keys()).sort();
+  for (const u of c) {
+    const p = i.get(u);
+    if (p === void 0)
+      continue;
+    const m = u.slice(u.indexOf(":") + 1), b = m !== "_null" ? m : null, v = Be(p, b, a);
+    for (const y of v)
+      s.push(Ce(y, r++, b, a));
+  }
+  return s;
+}
+function Ke(e, t) {
+  let n = 0;
+  for (const o of ne(e)) {
+    const i = e.milestones[o];
+    if (i === void 0)
+      continue;
+    const l = De(i.model, e, t) ?? 0;
+    n += l + (i.ki_estimate ?? 0);
+  }
+  return n;
+}
+function De(e, t, n) {
+  if (e === null)
+    return null;
+  const o = t.optimization.b_per_tier[e];
+  if (o != null)
+    return o;
+  const i = n.bPerTier[e];
+  return i !== void 0 ? i : null;
+}
+export {
+  Ke as computeTokensNaive,
+  Re as optimize,
+  Ne as snapshot,
+  $e as topoSortMilestones
+};

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { snapshot, topoSortMilestones } from './snapshot.js';
+export { optimize, computeTokensNaive } from './optimize.js';
+export type { IOptimizerDeps } from '@adhd/dispatch-base-spec';

package/lib/optimize/index.d.ts

@@ -0,0 +1 @@
+export { optimize, computeTokensNaive } from '../optimize.js';

package/lib/optimize.d.ts

@@ -0,0 +1,36 @@
+import { DagSnapshot, DispatchUnit, IOptimizerDeps } from '@adhd/dispatch-base-spec';
+
+/**
+ * Compute the greedy dispatch plan for the current scheduling cycle.
+ *
+ * Input: DagSnapshot — fully computed from snapshot().
+ * Output: DispatchUnit[] — one unit per batch assignment. Never mixes
+ *   shape.kind families or model tiers within one unit. Never contains a
+ *   unit whose tokens_estimated exceeds the tier's context window.
+ *
+ * Does not mutate the input snapshot.
+ */
+export declare function optimize(snapshot: DagSnapshot, deps: IOptimizerDeps): DispatchUnit[];
+/**
+ * Naive baseline (SCOPE.md §F4): one milestone = one agent call, no packing,
+ * no Sentinel-Fanout caching.
+ *
+ *   tokens_naive = Σ (b_per_tier[model] + ki_estimate) for each packable milestone
+ *
+ * Deliberately uses the RAW b_per_tier (not b_eff_per_tier) — the point of
+ * this baseline is "what would it cost with zero optimization applied",
+ * which specifically means no caching benefit either.
+ *
+ * The optimizer-core.2 shape.ops entry says to "emit tokens_naive... into
+ * the snapshot's optimization block" — but SnapshotOptimization (types.ts)
+ * has no tokens_naive field, and optimize()'s return type is fixed at
+ * DispatchUnit[], so there's no type-safe way to attach it to the snapshot
+ * from inside this module without either mutating the input (breaking the
+ * "does not mutate its input" contract) or editing @adhd/dispatch-base-spec
+ * (outside this milestone's file scope). This named export is the type-safe
+ * alternative: the value is computed, testable, and available to any caller
+ * that wants "packed vs naive". Adding a `tokens_naive` field to
+ * SnapshotOptimization belongs to a future @adhd/dispatch-base-spec change, not
+ * this file.
+ */
+export declare function computeTokensNaive(snapshot: DagSnapshot, deps: IOptimizerDeps): number;

package/lib/size-tokens.d.ts

@@ -0,0 +1,15 @@
+import { IOptimizerDeps } from '@adhd/dispatch-base-spec';
+
+/**
+ * Convert file bytes to an approximate token count.
+ * Source: SCOPE.md §C3 — byte-count is the right proxy (r>0.98, arxiv 2511.08066).
+ */
+export declare function siBytesAsTokens(bytes: number, filePath?: string): number;
+/**
+ * Batch-resolve file sizes via the injected deps.fileSizes callback.
+ *
+ * Graceful degradation: returns an empty map (every lookup then resolves to 0
+ * via `map.get(path) ?? 0` at the call site) when deps.fileSizes is undefined,
+ * the path list is empty, or the callback itself throws.
+ */
+export declare function lookupFileSizes(paths: string[], deps: IOptimizerDeps): Map<string, number>;

package/lib/snapshot/index.d.ts

@@ -0,0 +1 @@
+export { snapshot, topoSortMilestones } from '../snapshot.js';

package/lib/snapshot.d.ts

@@ -0,0 +1,35 @@
+import { DagJson, DagSnapshot, IOptimizerDeps, MilestoneDag } from '@adhd/dispatch-base-spec';
+
+/**
+ * Topologically sort milestone slugs and assign wave numbers.
+ * Uses Kahn's algorithm (BFS) for O(V+E).
+ *
+ * Wave 0: nodes with empty depends_on.
+ * Wave N: 1 + max(wave of deps).
+ * Ties within a wave are broken by slug (lexicographic) for determinism.
+ *
+ * @throws {Error} if a cycle is detected, including the cycle path.
+ */
+export declare function topoSortMilestones(milestones: Record<string, MilestoneDag>): {
+    order: string[];
+    waves: Map<string, number>;
+};
+/**
+ * Compute the fully-derived DagSnapshot from a dag.json document.
+ *
+ * Computation order (per SCOPE.md §N1):
+ *   1. Copy dag-level fields verbatim; resolve b_per_tier / context_window_per_tier
+ *      cold-start defaults from deps.
+ *   2. Compute b_eff_per_tier.
+ *   3. Topological sort → assign wave numbers.
+ *   4. Per-milestone derived fields.
+ *   5. Per-operation derived fields.
+ *   6. pairwise_overlap.
+ *   7. open_questions.
+ *
+ * Does not mutate the input dag.
+ *
+ * @throws {Error} if a dependency cycle is detected, or if the computed snapshot
+ *   fails structural validation (assertValidSnapshot).
+ */
+export declare function snapshot(dag: DagJson, deps: IOptimizerDeps): DagSnapshot;

package/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@adhd/dispatch-core-optimizer",
+  "version": "0.0.1",
+  "dependencies": {
+    "@adhd/dispatch-base-spec": "^0.0.1"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts"
+}

package/test/fixtures.d.ts

@@ -0,0 +1,21 @@
+import { DagJson, DispatchLogEntry, IOptimizerDeps, MilestoneDag, OperationDag } from '@adhd/dispatch-base-spec';
+
+/** Recommended cold-start defaults per SCOPE.md Open Decision #2. */
+export declare function defaultDeps(overrides?: Partial<IOptimizerDeps>): IOptimizerDeps;
+export declare function miniMilestone(overrides?: Partial<MilestoneDag>): MilestoneDag;
+export declare function miniOp(overrides?: Partial<OperationDag>): OperationDag;
+export declare function miniDag(overrides?: Partial<DagJson>): DagJson;
+/**
+ * Recursively Object.freeze a value and everything reachable from it (own
+ * enumerable keys only, arrays included). Functions are left unfrozen-and-
+ * unrecursed — freezing them adds nothing and isn't needed to prove data
+ * non-mutation.
+ *
+ * Used to prove snapshot()/optimize()/computeTokensNaive() honor their "does
+ * not mutate its input" contract: ES module code runs in strict mode, so any
+ * in-place write to a frozen object throws a TypeError instead of silently
+ * no-oping — a mutation bug turns into a failing test, not a passing one.
+ */
+export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): T;
+/** A dispatch_log entry recording a passed guard for `${slug}.guard`. */
+export declare function passingGuardEntry(slug: string, overrides?: Partial<DispatchLogEntry>): DispatchLogEntry;