mlx-bun 0.5.0 → 1.0.0

package/src/web/{sw.js → public/sw.js}

@@ -1,7 +1,8 @@
 // mlx-bun service worker — SHELL ONLY, not offline chat.
 //
-// Scope (plan §9 Phase 3, beat-matrix Axis 10 "PWA installability"):
-// installability + instant shell load. The app is useless without the
+// Scope (`02d723a:docs/design/web-chat-redesign.md` Appendix A,
+// beat-matrix Axis 10 "PWA installability"): installability + instant shell
+// load. The app is useless without the
 // local inference server actually running (every chat turn is a live
 // WebSocket to this same origin's model process), so caching API/WS
 // traffic would be actively misleading — a "successful" cached response
@@ -18,7 +19,7 @@
 //
 // Versioned by CACHE_NAME so a deploy invalidates old shells; bump the
 // suffix here if the shell file set changes.
-const CACHE_NAME = "mlxbun-shell-v2";
+const CACHE_NAME = "mlxbun-shell-monorepo-v1";
 const SHELL_FILES = [
   "/",
   "/assets/app.js",

package/src/web/{vendor → public/vendor}/hljs-theme.css

@@ -1,5 +1,5 @@
 /* Vendored highlight.js theme, hand-derived from mlx-bun's own design
- * tokens (see the :root / [data-theme="light"] blocks in src/web/app.html)
+ * tokens (see the :root / [data-theme="light"] blocks in apps/mlx-bun/src/web/public/app.html)
  * rather than one of highlight.js's stock themes — keeps code-block colors
  * on the same palette as the rest of the app in both themes. Code blocks
  * deliberately keep a dark chrome in BOTH themes (see app.html's
@@ -9,7 +9,7 @@
  *
  * Applies to `.bubble pre code.hljs` (see the highlightIn() hook in
  * app.html) — every `<span class="hljs-*">` produced by the vendored
- * hljs.js bundle (src/web/vendor/hljs.js, BSD-3-Clause, see its header).
+ * hljs.js bundle (apps/mlx-bun/src/web/public/vendor/hljs.js, BSD-3-Clause, see its header).
  */
 
 .bubble pre code.hljs{ display:block; }

package/src/web/{vendor → public/vendor}/hljs.js

@@ -16,10 +16,10 @@
  * permission. THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  * KIND. See the upstream LICENSE file for the full text.
  *
- * Rebuild: see src/web/vendor/README.md (or the header of this bundling
+ * Rebuild: see `02d723a:src/web/vendor/README.md` (or the header of this bundling
  * step in the mlx-bun repo) — `bun add highlight.js`, register the chosen
  * languages onto `highlight.js/lib/core`, `bun build --minify`.
- * NOT loaded from a CDN; served locally by src/server.ts.
+ * NOT loaded from a CDN; served locally by apps/mlx-bun/src/web/assets.ts.
  */
 var O3=Object.create;var{getPrototypeOf:A3,defineProperty:c1,getOwnPropertyNames:p3}=Object;var u3=Object.prototype.hasOwnProperty;function j3(z){return this[z]}var N3,R3,_3=(z,Z,q)=>{var V=z!=null&&typeof z==="object";if(V){var y=Z?N3??=new WeakMap:R3??=new WeakMap,k=y.get(z);if(k)return k}q=z!=null?O3(A3(z)):{};let Q=Z||!z||!z.__esModule?c1(q,"default",{value:z,enumerable:!0}):q;for(let J of p3(z))if(!u3.call(Q,J))c1(Q,J,{get:j3.bind(z,J),enumerable:!0});if(V)y.set(z,Q);return Q};var c3=(z,Z)=>()=>(Z||z((Z={exports:{}}).exports,Z),Z.exports);var v3=c3((E5,$3)=>{function h1(z){if(z instanceof Map)z.clear=z.delete=z.set=function(){throw Error("map is read-only")};else if(z instanceof Set)z.add=z.clear=z.delete=function(){throw Error("set is read-only")};return Object.freeze(z),Object.getOwnPropertyNames(z).forEach((Z)=>{let q=z[Z],V=typeof q;if((V==="object"||V==="function")&&!Object.isFrozen(q))h1(q)}),z}class w1{constructor(z){if(z.data===void 0)z.data={};this.data=z.data,this.isMatchIgnored=!1}ignoreMatch(){this.isMatchIgnored=!0}}function d1(z){return z.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#x27;")}function t(z,...Z){let q=Object.create(null);for(let V in z)q[V]=z[V];return Z.forEach(function(V){for(let y in V)q[y]=V[y]}),q}var S3="</span>",S1=(z)=>{return!!z.scope},T3=(z,{prefix:Z})=>{if(z.startsWith("language:"))return z.replace("language:","language-");if(z.includes(".")){let q=z.split(".");return[`${Z}${q.shift()}`,...q.map((V,y)=>`${V}${"_".repeat(y+1)}`)].join(" ")}return`${Z}${z}`};class r1{constructor(z,Z){this.buffer="",this.classPrefix=Z.classPrefix,z.walk(this)}addText(z){this.buffer+=d1(z)}openNode(z){if(!S1(z))return;let Z=T3(z.scope,{prefix:this.classPrefix});this.span(Z)}closeNode(z){if(!S1(z))return;this.buffer+=S3}value(){return this.buffer}span(z){this.buffer+=`<span class="${z}">`}}var T1=(z={})=>{let Z={children:[]};return Object.assign(Z,z),Z};class b1{constructor(){this.rootNode=T1(),this.stack=[this.rootNode]}get top(){return this.stack[this.stack.length-1]}get root(){return this.rootNode}add(z){this.top.children.push(z)}openNode(z){let Z=T1({scope:z});this.add(Z),this.stack.push(Z)}closeNode(){if(this.stack.length>1)return this.stack.pop();return}closeAllNodes(){while(this.closeNode());}toJSON(){return JSON.stringify(this.rootNode,null,4)}walk(z){return this.constructor._walk(z,this.rootNode)}static _walk(z,Z){if(typeof Z==="string")z.addText(Z);else if(Z.children)z.openNode(Z),Z.children.forEach((q)=>this._walk(z,q)),z.closeNode(Z);return z}static _collapse(z){if(typeof z==="string")return;if(!z.children)return;if(z.children.every((Z)=>typeof Z==="string"))z.children=[z.children.join("")];else z.children.forEach((Z)=>{b1._collapse(Z)})}}class m1 extends b1{constructor(z){super();this.options=z}addText(z){if(z==="")return;this.add(z)}startScope(z){this.openNode(z)}endScope(){this.closeNode()}__addSublanguage(z,Z){let q=z.root;if(Z)q.scope=`language:${Z}`;this.add(q)}toHTML(){return new r1(this,this.options).value()}finalize(){return this.closeAllNodes(),!0}}function $1(z){if(!z)return null;if(typeof z==="string")return z;return z.source}function t1(z){return s("(?=",z,")")}function i3(z){return s("(?:",z,")*")}function E3(z){return s("(?:",z,")?")}function s(...z){return z.map((q)=>$1(q)).join("")}function g3(z){let Z=z[z.length-1];if(typeof Z==="object"&&Z.constructor===Object)return z.splice(z.length-1,1),Z;else return{}}function f1(...z){return"("+(g3(z).capture?"":"?:")+z.map((V)=>$1(V)).join("|")+")"}function l1(z){return new RegExp(z.toString()+"|").exec("").length-1}function n3(z,Z){let q=z&&z.exec(Z);return q&&q.index===0}var h3=/\[(?:[^\\\]]|\\.)*\]|\(\??|\\([1-9][0-9]*)|\\./;function U1(z,{joinWith:Z}){let q=0;return z.map((V)=>{q+=1;let y=q,k=$1(V),Q="";while(k.length>0){let J=h3.exec(k);if(!J){Q+=k;break}if(Q+=k.substring(0,J.index),k=k.substring(J.index+J[0].length),J[0][0]==="\\"&&J[1])Q+="\\"+String(Number(J[1])+y);else if(Q+=J[0],J[0]==="(")q++}return Q}).map((V)=>`(${V})`).join(Z)}var d3=/\b\B/,a1="[a-zA-Z]\\w*",B1="[a-zA-Z_]\\w*",s1="\\b\\d+(\\.\\d+)?",o1="(-?)(\\b0[xX][a-fA-F0-9]+|(\\b\\d+(\\.\\d*)?|\\.\\d+)([eE][-+]?\\d+)?)",e1="\\b(0b[01]+)",r3="!|!=|!==|%|%=|&|&&|&=|\\*|\\*=|\\+|\\+=|,|-|-=|/=|/|:|;|<<|<<=|<=|<|===|==|=|>>>=|>>=|>=|>>>|>>|>|\\?|\\[|\\{|\\(|\\^|\\^=|\\||\\|=|\\|\\||~",m3=(z={})=>{let Z=/^#![ ]*\//;if(z.binary)z.begin=s(Z,/.*\b/,z.binary,/\b.*/);return t({scope:"meta",begin:Z,end:/$/,relevance:0,"on:begin":(q,V)=>{if(q.index!==0)V.ignoreMatch()}},z)},v1={begin:"\\\\[\\s\\S]",relevance:0},t3={scope:"string",begin:"'",end:"'",illegal:"\\n",contains:[v1]},l3={scope:"string",begin:'"',end:'"',illegal:"\\n",contains:[v1]},a3={begin:/\b(a|an|the|are|I'm|isn't|don't|doesn't|won't|but|just|should|pretty|simply|enough|gonna|going|wtf|so|such|will|you|your|they|like|more)\b/},y1=function(z,Z,q={}){let V=t({scope:"comment",begin:z,end:Z,contains:[]},q);V.contains.push({scope:"doctag",begin:"[ ]*(?=(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):)",end:/(TODO|FIXME|NOTE|BUG|OPTIMIZE|HACK|XXX):/,excludeBegin:!0,relevance:0});let y=f1("I","a","is","so","us","to","at","if","in","it","on",/[A-Za-z]+['](d|ve|re|ll|t|s|n)/,/[A-Za-z]+[-][a-z]+/,/[A-Za-z][a-z]{2,}/);return V.contains.push({begin:s(/[ ]+/,"(",y,/[.]?[:]?([.][ ]|[ ])/,"){3}")}),V},s3=y1("//","$"),o3=y1("/\\*","\\*/"),e3=y1("#","$"),z5={scope:"number",begin:s1,relevance:0},Z5={scope:"number",begin:o1,relevance:0},q5={scope:"number",begin:e1,relevance:0},J5={scope:"regexp",begin:/\/(?=[^/\n]*\/)/,end:/\/[gimuy]*/,contains:[v1,{begin:/\[/,end:/\]/,relevance:0,contains:[v1]}]},Q5={scope:"title",begin:a1,relevance:0},$5={scope:"title",begin:B1,relevance:0},v5={begin:"\\.\\s*"+B1,relevance:0},V5=function(z){return Object.assign(z,{"on:begin":(Z,q)=>{q.data._beginMatch=Z[1]},"on:end":(Z,q)=>{if(q.data._beginMatch!==Z[1])q.ignoreMatch()}})},W1=Object.freeze({__proto__:null,APOS_STRING_MODE:t3,BACKSLASH_ESCAPE:v1,BINARY_NUMBER_MODE:q5,BINARY_NUMBER_RE:e1,COMMENT:y1,C_BLOCK_COMMENT_MODE:o3,C_LINE_COMMENT_MODE:s3,C_NUMBER_MODE:Z5,C_NUMBER_RE:o1,END_SAME_AS_BEGIN:V5,HASH_COMMENT_MODE:e3,IDENT_RE:a1,MATCH_NOTHING_RE:d3,METHOD_GUARD:v5,NUMBER_MODE:z5,NUMBER_RE:s1,PHRASAL_WORDS_MODE:a3,QUOTE_STRING_MODE:l3,REGEXP_MODE:J5,RE_STARTERS_RE:r3,SHEBANG:m3,TITLE_MODE:Q5,UNDERSCORE_IDENT_RE:B1,UNDERSCORE_TITLE_MODE:$5});function X5(z,Z){if(z.input[z.index-1]===".")Z.ignoreMatch()}function F5(z,Z){if(z.className!==void 0)z.scope=z.className,delete z.className}function W5(z,Z){if(!Z)return;if(!z.beginKeywords)return;if(z.begin="\\b("+z.beginKeywords.split(" ").join("|")+")(?!\\.)(?=\\b|\\s)",z.__beforeBegin=X5,z.keywords=z.keywords||z.beginKeywords,delete z.beginKeywords,z.relevance===void 0)z.relevance=0}function Y5(z,Z){if(!Array.isArray(z.illegal))return;z.illegal=f1(...z.illegal)}function y5(z,Z){if(!z.match)return;if(z.begin||z.end)throw Error("begin & end are not supported with match");z.begin=z.match,delete z.match}function k5(z,Z){if(z.relevance===void 0)z.relevance=1}var H5=(z,Z)=>{if(!z.beforeMatch)return;if(z.starts)throw Error("beforeMatch cannot be used with starts");let q=Object.assign({},z);Object.keys(z).forEach((V)=>{delete z[V]}),z.keywords=q.keywords,z.begin=s(q.beforeMatch,t1(q.begin)),z.starts={relevance:0,contains:[Object.assign(q,{endsParent:!0})]},z.relevance=0,delete q.beforeMatch},K5=["of","and","for","in","not","or","if","then","parent","list","value"],G5="keyword";function z3(z,Z,q=G5){let V=Object.create(null);if(typeof z==="string")y(q,z.split(" "));else if(Array.isArray(z))y(q,z);else Object.keys(z).forEach(function(k){Object.assign(V,z3(z[k],Z,k))});return V;function y(k,Q){if(Z)Q=Q.map((J)=>J.toLowerCase());Q.forEach(function(J){let X=J.split("|");V[X[0]]=[k,w5(X[0],X[1])]})}}function w5(z,Z){if(Z)return Number(Z);return b5(z)?0:1}function b5(z){return K5.includes(z.toLowerCase())}var i1={},a=(z)=>{console.error(z)},E1=(z,...Z)=>{console.log(`WARN: ${z}`,...Z)},e=(z,Z)=>{if(i1[`${z}/${Z}`])return;console.log(`Deprecated as of ${z}. ${Z}`),i1[`${z}/${Z}`]=!0},Y1=Error();function Z3(z,Z,{key:q}){let V=0,y=z[q],k={},Q={};for(let J=1;J<=Z.length;J++)Q[J+V]=y[J],k[J+V]=!0,V+=l1(Z[J-1]);z[q]=Q,z[q]._emit=k,z[q]._multi=!0}function f5(z){if(!Array.isArray(z.begin))return;if(z.skip||z.excludeBegin||z.returnBegin)throw a("skip, excludeBegin, returnBegin not compatible with beginScope: {}"),Y1;if(typeof z.beginScope!=="object"||z.beginScope===null)throw a("beginScope must be object"),Y1;Z3(z,z.begin,{key:"beginScope"}),z.begin=U1(z.begin,{joinWith:""})}function U5(z){if(!Array.isArray(z.end))return;if(z.skip||z.excludeEnd||z.returnEnd)throw a("skip, excludeEnd, returnEnd not compatible with endScope: {}"),Y1;if(typeof z.endScope!=="object"||z.endScope===null)throw a("endScope must be object"),Y1;Z3(z,z.end,{key:"endScope"}),z.end=U1(z.end,{joinWith:""})}function B5(z){if(z.scope&&typeof z.scope==="object"&&z.scope!==null)z.beginScope=z.scope,delete z.scope}function x5(z){if(B5(z),typeof z.beginScope==="string")z.beginScope={_wrap:z.beginScope};if(typeof z.endScope==="string")z.endScope={_wrap:z.endScope};f5(z),U5(z)}function P5(z){function Z(Q,J){return new RegExp($1(Q),"m"+(z.case_insensitive?"i":"")+(z.unicodeRegex?"u":"")+(J?"g":""))}class q{constructor(){this.matchIndexes={},this.regexes=[],this.matchAt=1,this.position=0}addRule(Q,J){J.position=this.position++,this.matchIndexes[this.matchAt]=J,this.regexes.push([J,Q]),this.matchAt+=l1(Q)+1}compile(){if(this.regexes.length===0)this.exec=()=>null;let Q=this.regexes.map((J)=>J[1]);this.matcherRe=Z(U1(Q,{joinWith:"|"}),!0),this.lastIndex=0}exec(Q){this.matcherRe.lastIndex=this.lastIndex;let J=this.matcherRe.exec(Q);if(!J)return null;let X=J.findIndex((K,U)=>U>0&&K!==void 0),H=this.matchIndexes[X];return J.splice(0,X),Object.assign(J,H)}}class V{constructor(){this.rules=[],this.multiRegexes=[],this.count=0,this.lastIndex=0,this.regexIndex=0}getMatcher(Q){if(this.multiRegexes[Q])return this.multiRegexes[Q];let J=new q;return this.rules.slice(Q).forEach(([X,H])=>J.addRule(X,H)),J.compile(),this.multiRegexes[Q]=J,J}resumingScanAtSamePosition(){return this.regexIndex!==0}considerAll(){this.regexIndex=0}addRule(Q,J){if(this.rules.push([Q,J]),J.type==="begin")this.count++}exec(Q){let J=this.getMatcher(this.regexIndex);J.lastIndex=this.lastIndex;let X=J.exec(Q);if(this.resumingScanAtSamePosition())if(X&&X.index===this.lastIndex);else{let H=this.getMatcher(0);H.lastIndex=this.lastIndex+1,X=H.exec(Q)}if(X){if(this.regexIndex+=X.position+1,this.regexIndex===this.count)this.considerAll()}return X}}function y(Q){let J=new V;if(Q.contains.forEach((X)=>J.addRule(X.begin,{rule:X,type:"begin"})),Q.terminatorEnd)J.addRule(Q.terminatorEnd,{type:"end"});if(Q.illegal)J.addRule(Q.illegal,{type:"illegal"});return J}function k(Q,J){let X=Q;if(Q.isCompiled)return X;[F5,y5,x5,H5].forEach((K)=>K(Q,J)),z.compilerExtensions.forEach((K)=>K(Q,J)),Q.__beforeBegin=null,[W5,Y5,k5].forEach((K)=>K(Q,J)),Q.isCompiled=!0;let H=null;if(typeof Q.keywords==="object"&&Q.keywords.$pattern)Q.keywords=Object.assign({},Q.keywords),H=Q.keywords.$pattern,delete Q.keywords.$pattern;if(H=H||/\w+/,Q.keywords)Q.keywords=z3(Q.keywords,z.case_insensitive);if(X.keywordPatternRe=Z(H,!0),J){if(!Q.begin)Q.begin=/\B|\b/;if(X.beginRe=Z(X.begin),!Q.end&&!Q.endsWithParent)Q.end=/\B|\b/;if(Q.end)X.endRe=Z(X.end);if(X.terminatorEnd=$1(X.end)||"",Q.endsWithParent&&J.terminatorEnd)X.terminatorEnd+=(Q.end?"|":"")+J.terminatorEnd}if(Q.illegal)X.illegalRe=Z(Q.illegal);if(!Q.contains)Q.contains=[];if(Q.contains=[].concat(...Q.contains.map(function(K){return D5(K==="self"?Q:K)})),Q.contains.forEach(function(K){k(K,X)}),Q.starts)k(Q.starts,J);return X.matcher=y(X),X}if(!z.compilerExtensions)z.compilerExtensions=[];if(z.contains&&z.contains.includes("self"))throw Error("ERR: contains `self` is not supported at the top-level of a language.  See documentation.");return z.classNameAliases=t(z.classNameAliases||{}),k(z)}function q3(z){if(!z)return!1;return z.endsWithParent||q3(z.starts)}function D5(z){if(z.variants&&!z.cachedVariants)z.cachedVariants=z.variants.map(function(Z){return t(z,{variants:null},Z)});if(z.cachedVariants)return z.cachedVariants;if(q3(z))return t(z,{starts:z.starts?t(z.starts):null});if(Object.isFrozen(z))return t(z);return z}var C5="11.11.1";class J3 extends Error{constructor(z,Z){super(z);this.name="HTMLInjectionError",this.html=Z}}var G1=d1,g1=t,n1=Symbol("nomatch"),L5=7,Q3=function(z){let Z=Object.create(null),q=Object.create(null),V=[],y=!0,k="Could not find the language '{}', did you forget to load/include a language module?",Q={disableAutodetect:!0,name:"Plain text",contains:[]},J={ignoreUnescapedHTML:!1,throwUnescapedHTML:!1,noHighlightRe:/^(no-?highlight)$/i,languageDetectRe:/\blang(?:uage)?-([\w-]+)\b/i,classPrefix:"hljs-",cssSelector:"pre code",languages:null,__emitter:m1};function X($){return J.noHighlightRe.test($)}function H($){let W=$.className+" ";W+=$.parentNode?$.parentNode.className:"";let F=J.languageDetectRe.exec(W);if(F){let w=R(F[1]);if(!w)E1(k.replace("{}",F[1])),E1("Falling back to no-highlight mode for this block.",$);return w?F[1]:"no-highlight"}return W.split(/\s+/).find((w)=>X(w)||R(w))}function K($,W,F){let w="",B="";if(typeof W==="object")w=$,F=W.ignoreIllegals,B=W.language;else e("10.7.0","highlight(lang, code, ...args) has been deprecated."),e("10.7.0",`Please use highlight(code, options) instead.
 https://github.com/highlightjs/highlight.js/issues/2277`),B=$,w=W;if(F===void 0)F=!0;let j={code:w,language:B};m("before:highlight",j);let c=j.result?j.result:U(j.language,j.code,F);return c.code=j.code,m("after:highlight",c),c}function U($,W,F,w){let B=Object.create(null);function j(v,Y){return v.keywords[Y]}function c(){if(!G.keywords){_.addText(L);return}let v=0;G.keywordPatternRe.lastIndex=0;let Y=G.keywordPatternRe.exec(L),b="";while(Y){b+=L.substring(v,Y.index);let C=h.case_insensitive?Y[0].toLowerCase():Y[0],S=j(G,C);if(S){let[r,M3]=S;if(_.addText(b),b="",B[C]=(B[C]||0)+1,B[C]<=L5)F1+=M3;if(r.startsWith("_"))b+=Y[0];else{let I3=h.classNameAliases[r]||r;n(Y[0],I3)}}else b+=Y[0];v=G.keywordPatternRe.lastIndex,Y=G.keywordPatternRe.exec(L)}b+=L.substring(v),_.addText(b)}function g(){if(L==="")return;let v=null;if(typeof G.subLanguage==="string"){if(!Z[G.subLanguage]){_.addText(L);return}v=U(G.subLanguage,L,!0,_1[G.subLanguage]),_1[G.subLanguage]=v._top}else v=f(L,G.subLanguage.length?G.subLanguage:null);if(G.relevance>0)F1+=v.relevance;_.__addSublanguage(v._emitter,v.language)}function E(){if(G.subLanguage!=null)g();else c();L=""}function n(v,Y){if(v==="")return;_.startScope(Y),_.addText(v),_.endScope()}function u1(v,Y){let b=1,C=Y.length-1;while(b<=C){if(!v._emit[b]){b++;continue}let S=h.classNameAliases[v[b]]||v[b],r=Y[b];if(S)n(r,S);else L=r,c(),L="";b++}}function j1(v,Y){if(v.scope&&typeof v.scope==="string")_.openNode(h.classNameAliases[v.scope]||v.scope);if(v.beginScope){if(v.beginScope._wrap)n(L,h.classNameAliases[v.beginScope._wrap]||v.beginScope._wrap),L="";else if(v.beginScope._multi)u1(v.beginScope,Y),L=""}return G=Object.create(v,{parent:{value:G}}),G}function N1(v,Y,b){let C=n3(v.endRe,b);if(C){if(v["on:end"]){let S=new w1(v);if(v["on:end"](Y,S),S.isMatchIgnored)C=!1}if(C){while(v.endsParent&&v.parent)v=v.parent;return v}}if(v.endsWithParent)return N1(v.parent,Y,b)}function x3(v){if(G.matcher.regexIndex===0)return L+=v[0],1;else return K1=!0,0}function P3(v){let Y=v[0],b=v.rule,C=new w1(b),S=[b.__beforeBegin,b["on:begin"]];for(let r of S){if(!r)continue;if(r(v,C),C.isMatchIgnored)return x3(Y)}if(b.skip)L+=Y;else{if(b.excludeBegin)L+=Y;if(E(),!b.returnBegin&&!b.excludeBegin)L=Y}return j1(b,v),b.returnBegin?0:Y.length}function D3(v){let Y=v[0],b=W.substring(v.index),C=N1(G,v,b);if(!C)return n1;let S=G;if(G.endScope&&G.endScope._wrap)E(),n(Y,G.endScope._wrap);else if(G.endScope&&G.endScope._multi)E(),u1(G.endScope,v);else if(S.skip)L+=Y;else{if(!(S.returnEnd||S.excludeEnd))L+=Y;if(E(),S.excludeEnd)L=Y}do{if(G.scope)_.closeNode();if(!G.skip&&!G.subLanguage)F1+=G.relevance;G=G.parent}while(G!==C.parent);if(C.starts)j1(C.starts,v);return S.returnEnd?0:Y.length}function C3(){let v=[];for(let Y=G;Y!==h;Y=Y.parent)if(Y.scope)v.unshift(Y.scope);v.forEach((Y)=>_.openNode(Y))}let X1={};function R1(v,Y){let b=Y&&Y[0];if(L+=v,b==null)return E(),0;if(X1.type==="begin"&&Y.type==="end"&&X1.index===Y.index&&b===""){if(L+=W.slice(Y.index,Y.index+1),!y){let C=Error(`0 width match regex (${$})`);throw C.languageName=$,C.badRule=X1.rule,C}return 1}if(X1=Y,Y.type==="begin")return P3(Y);else if(Y.type==="illegal"&&!F){let C=Error('Illegal lexeme "'+b+'" for mode "'+(G.scope||"<unnamed>")+'"');throw C.mode=G,C}else if(Y.type==="end"){let C=D3(Y);if(C!==n1)return C}if(Y.type==="illegal"&&b==="")return L+=`

package/THIRD_PARTY_LICENSES.md

@@ -1,51 +0,0 @@
-# Third-party licenses
-
-mlx-bun is MIT-licensed. It builds on, links against, and ports code
-from the following projects.
-
-## Linked libraries
-
-| Project | License | Use |
-|---|---|---|
-| [MLX](https://github.com/ml-explore/mlx) (Apple) | MIT | All GPU compute — Metal kernels, lazy eval engine (`libmlx`) |
-| [mlx-c](https://github.com/ml-explore/mlx-c) (Apple) | MIT | C API we bind via `bun:ffi` (`libmlxc.dylib`, installed via Homebrew) |
-
-## Ported code
-
-These files are TypeScript ports of Python sources; the port preserves
-the upstream algorithm and is a derivative work of the original.
-
-| Source | License | Ported into |
-|---|---|---|
-| [mlx-lm](https://github.com/ml-explore/mlx-lm) (Apple, MIT) — `models/gemma4_text.py`, `models/cache.py`, `models/base.py`, `models/rope_utils.py`, `sample_utils.py`, `tool_parsers/gemma4.py` | MIT | `src/model/gemma4.ts`, `src/sampler.ts`, `src/tool-call.ts` |
-| [mlx-vlm](https://github.com/Blaizzy/mlx-vlm) (BSD-3-Clause) — Gemma-4 unified `VisionEmbedder`, `MultimodalEmbedder`, image preprocessing (as vendored in mlx-optiq) | BSD-3-Clause | `src/vision/embedder.ts`, `src/vision/preprocess.ts` |
-| mlx-optiq (MIT) — vision sidecar wiring, fused quantized SDPA orchestration | MIT | `src/vision/`, quantized-KV paths in `src/model/gemma4.ts` |
-| [Pillow](https://github.com/python-pillow/Pillow) (MIT-CMU / HPND) — `ImagingResample` bicubic convolution algorithm | HPND | `resizeBicubic` in `src/vision/preprocess.ts` (algorithm port) |
-| [Colibri](https://github.com/JustVugg/colibri) (pinned development oracle `44e489b196c9b7876b3d37a0570ebf1c6f90f54c`) — direct-container layout, expert-residency/I/O policy, GLM-5.2 execution and Metal-kernel reference | Apache-2.0 | Native GLM-5.2 implementation under `src/model/glm52-*`, `src/expert-*`, and `src/native/expert_io.c`; rewritten for Bun + MLX, with direct Colibri retained only as an external oracle |
-
-## Runtime npm dependencies
-
-| Package | License | Use |
-|---|---|---|
-| `@huggingface/tokenizers` | Apache-2.0 | Pure-JS tokenizer (tokenizer.json) |
-| `@huggingface/jinja` | MIT | Chat-template rendering |
-| `fast-png` | MIT | PNG decode (raw pixels for the vision path) |
-| `@mlc-ai/web-xgrammar` | Apache-2.0 | Grammar-constrained decoding (WASM build of [xgrammar](https://github.com/mlc-ai/xgrammar) by the MLC-ai team). `response_format` / `guided_grammar` / `guided_regex` / `guided_choice` compile to a GrammarMatcher whose per-step token bitmask masks invalid logits (`src/grammar.ts`). Idea ported from oMLX (`api/grammar.py`), same engine, WASM-packaged. |
-
-Run `bun pm licenses` (or inspect `node_modules/*/LICENSE`) for the full
-text of each npm dependency's license, including transitive ones.
-
-## Models
-
-Model weights (e.g. `mlx-community/gemma-4-12B-it-OptiQ-4bit`) are not
-part of this repository and are governed by their own licenses and use
-policies (e.g. Google's Gemma Terms of Use). Check the model card on
-Hugging Face before redistribution.
-
-The validated GLM-5.2 direct-container artifact,
-[`mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp`](https://huggingface.co/mateogrgic/GLM-5.2-colibri-int4-with-int8-mtp),
-declares MIT and identifies itself as a Colibri conversion/derivative of
-[`zai-org/GLM-5.2-FP8`](https://huggingface.co/zai-org/GLM-5.2-FP8), with
-lineage through `jlnsrk/GLM-5.2-colibri-int4` and added int8 MTP weights. The
-artifact is downloaded separately into the Hugging Face cache and is not part
-of the mlx-bun distribution.

package/docs/README.md

@@ -1,107 +0,0 @@
-# Documentation
-
-Generated index. Update with `bun scripts/check-hygiene.ts --write-docs-map`.
-
-## Start here
-
-- Run mlx-bun: [quickstart](../README.md#quickstart), [models](reference/models.md), [CLI](reference/cli.md), [troubleshooting](reference/troubleshooting.md).
-- Build an application: [TypeScript library](reference/library-api.md), [HTTP API](reference/server-api.md), [server configuration](reference/server-config.md).
-- Assess the results: [benchmarks and correctness evidence](reference/benchmarks.md).
-- Contribute: [contribution guide](../CONTRIBUTING.md), [engine architecture](design/unified-engine-frontier-plan.md), [current work](../PLAN.md).
-
-## docs/reference/
-
-User-facing reference — the ONLY home for flags, routes, models, numbers, and environment facts.
-
-- [benchmarks.md](../docs/reference/benchmarks.md) — mlx-bun benchmark results
-- [cli.md](../docs/reference/cli.md) — CLI reference
-- [distribution.md](../docs/reference/distribution.md) — Distributing mlx-bun — build, sign, notarize, publish
-- [environment.md](../docs/reference/environment.md) — Reference environment and platform facts
-- [glossary.md](../docs/reference/glossary.md) — mlx-bun serving
-- [library-api.md](../docs/reference/library-api.md) — Library API
-- [memory.md](../docs/reference/memory.md) — Memory — the personal wiki
-- [models.md](../docs/reference/models.md) — Models: supported roster + management (get / scan / ls / gc)
-- [server-api.md](../docs/reference/server-api.md) — Server API
-- [server-config.md](../docs/reference/server-config.md) — Server configuration
-- [training.md](../docs/reference/training.md) — Training / fine-tuning reference
-- [troubleshooting.md](../docs/reference/troubleshooting.md) — Troubleshooting
-
-## docs/design/
-
-Active engineering design docs — one per topic; status lives in front matter + PLAN.md.
-
-- [batching.md](../docs/design/batching.md) — Batching — continuous scheduling for `--batch N`
-- [decode-speed-program.md](../docs/design/decode-speed-program.md) — Inference performance program
-- [dreaming-nightly-pipeline.md](../docs/design/dreaming-nightly-pipeline.md) — The Dreaming — memory write path + synthesis (canonical design)
-- [generic-model-support.md](../docs/design/generic-model-support.md) — Model support — run anything mlx-lm runs, and the ports we target
-- [kv-cache.md](../docs/design/kv-cache.md) — KV cache — residency and layout
-- [orpo-training.md](../docs/design/orpo-training.md) — Training — design (ORPO, flash-CCE head, prefix sharing, segmented backward)
-- [speculative-decoding.md](../docs/design/speculative-decoding.md) — Speculative decoding — one verifier, every draft source
-- [turboquant.md](../docs/design/turboquant.md) — TurboQuant — rotation-based quantization (KV leg landed, weights leg open)
-- [unified-engine-frontier-plan.md](../docs/design/unified-engine-frontier-plan.md) — Engine architecture — four layers, per-scheme oracles, one request path
-- [web-chat-redesign.md](../docs/design/web-chat-redesign.md) — Web chat — the built-in chat surface (canonical design)
-
-## docs/planning/
-
-Living product/vision docs (USING side).
-
-- [PRODUCT_ROADMAP.md](../docs/planning/PRODUCT_ROADMAP.md) — PRODUCT ROADMAP
-- [ResearchTopics.md](../docs/planning/ResearchTopics.md) — Research Topics
-- [public-readiness-handoff.md](../docs/planning/public-readiness-handoff.md) — Public readiness — handoff (2026-09-11)
-- [public-readiness.md](../docs/planning/public-readiness.md) — Preparing mlx-bun for the MLX community
-- [video-series.md](../docs/planning/video-series.md) — mlx-bun video series
-
-## docs/archive/
-
-Frozen history — read-only, never extended in place; recover raw data via git history.
-
-- [hlg-sampling.md](../docs/archive/hlg-sampling.md) — HLG sampling — a piecewise tone curve on the logits
-- [investigations/audio-input-plan.md](../docs/archive/investigations/audio-input-plan.md) — Audio input — design & implementation plan (gemma-4 audio tower)
-- [investigations/benchmark-ledger-through-v0.4.0.md](../docs/archive/investigations/benchmark-ledger-through-v0.4.0.md) — Benchmark ledger through v0.4.0
-- [investigations/chunk-finetune-experiment.md](../docs/archive/investigations/chunk-finetune-experiment.md) — Fine-tuning experiment: chunking task (2026-06-16)
-- [investigations/colibri-glm52-port.md](../docs/archive/investigations/colibri-glm52-port.md) — GLM-5.2 on a 32 GB Mac — native MLX port of the Colibri hierarchy
-- [investigations/colibri-oracle-pin.md](../docs/archive/investigations/colibri-oracle-pin.md) — Colibri oracle pin for the native GLM-5.2 port
-- [investigations/curve-bisector-routing.md](../docs/archive/investigations/curve-bisector-routing.md) — Curve sampler: bisectors, routing, and the falsification
-- [investigations/decode-roofline-lookagain.md](../docs/archive/investigations/decode-roofline-lookagain.md) — Decode perf "look again" — adversarial re-exam of the M=1 floor claim (2026-07-01)
-- [investigations/diffusion-gemma-port.md](../docs/archive/investigations/diffusion-gemma-port.md) — DiffusionGemma port — plan & parity strategy
-- [investigations/dspark-handoff.md](../docs/archive/investigations/dspark-handoff.md) — DSpark — handoff
-- [investigations/expert-offload-single-user-moe.md](../docs/archive/investigations/expert-offload-single-user-moe.md) — Expert offload for single-user local MoE — findings + design sketch
-- [investigations/faithful-l1-consolidation.md](../docs/archive/investigations/faithful-l1-consolidation.md) — Faithful → L1: consolidating the "match mlx-lm" path
-- [investigations/hlg-sampling-investigation.md](../docs/archive/investigations/hlg-sampling-investigation.md) — Investigation: HLG sampling — a piecewise tone curve on the logits
-- [investigations/indexshare-performance-spike.md](../docs/archive/investigations/indexshare-performance-spike.md) — IndexShare / IndexCache performance spike
-- [investigations/kernel-perf-review-2026-07.md](../docs/archive/investigations/kernel-perf-review-2026-07.md) — Kernel/perf deep review — 2026-07-01 (condensed, tracked record)
-- [investigations/lab-build-journal.md](../docs/archive/investigations/lab-build-journal.md) — Build journal — mlx-bun Lab (web UI + native quantize/train/dataset + pi web chat)
-- [investigations/minicpm5-decode-megakernel.md](../docs/archive/investigations/minicpm5-decode-megakernel.md) — MiniCPM5 Decode Megakernel — end-to-end build plan (handoff)
-- [investigations/openjarvis-fit.md](../docs/archive/investigations/openjarvis-fit.md) — OpenJarvis research and fit with mlx-bun
-- [investigations/openwiki-evaluation.md](../docs/archive/investigations/openwiki-evaluation.md) — OpenWiki — evaluation & fit analysis
-- [investigations/optimization_plan.md](../docs/archive/investigations/optimization_plan.md) — mlx-bun: gemma4.ts decompose & optimize — action plan
-- [investigations/orpo-base-uf-experiment-and-directions.md](../docs/archive/investigations/orpo-base-uf-experiment-and-directions.md) — ORPO from-base on UltraFeedback (mixed-5bpw) — results + research directions
-- [investigations/orpo-flash-cce-pin-leak.md](../docs/archive/investigations/orpo-flash-cce-pin-leak.md) — flash-CCE host-buffer pin leak — post-mortem + L3 verification approach
-- [investigations/orpo-uf-testing-handoff.md](../docs/archive/investigations/orpo-uf-testing-handoff.md) — ORPO-on-UF — results + testing-phase handoff
-- [investigations/pareto-specialized-runtime-findings.md](../docs/archive/investigations/pareto-specialized-runtime-findings.md) — Pareto-specialized runtime findings
-- [investigations/pi-builtin-investigation.md](../docs/archive/investigations/pi-builtin-investigation.md) — Investigation: pi as a "built-in" terminal for mlx-bun
-- [investigations/pre-colibri-stabilization.md](../docs/archive/investigations/pre-colibri-stabilization.md) — Pre-Colibri stabilization program
-- [investigations/qwen38-27b-campaign-log.md](../docs/archive/investigations/qwen38-27b-campaign-log.md) — Qwen3.8-27B optimization campaign — execution log (2026-09-04 → 2026-09-08)
-- [investigations/segmented-backward-handoff.md](../docs/archive/investigations/segmented-backward-handoff.md) — Handoff — segmented backward training (2026-06-16)
-- [investigations/starter-model-port-handoff.md](../docs/archive/investigations/starter-model-port-handoff.md) — Handoff: the sub-GB starter model port (publishing gate 1)
-- [investigations/steel-flash-cce-handoff.md](../docs/archive/investigations/steel-flash-cce-handoff.md) — Steel flash-CCE — handoff
-- [investigations/the-dreaming-handoff.md](../docs/archive/investigations/the-dreaming-handoff.md) — THE DREAMING — HANDOFF (2026-06-28)
-- [investigations/trainer-validation-experiment.md](../docs/archive/investigations/trainer-validation-experiment.md) — Trainer validation experiment
-- [planning/chat-ui-vision-memory-first.md](../docs/archive/planning/chat-ui-vision-memory-first.md) — Chat UI Vision: The Model That Knows You
-- [planning/chat-ui-vision.md](../docs/archive/planning/chat-ui-vision.md) — The mlx-bun chat surface: a vision
-- [planning/chunk-task-roadmap.md](../docs/archive/planning/chunk-task-roadmap.md) — Chunk-task quality roadmap (2026-06-17)
-- [planning/curve-sampler-research-plan.md](../docs/archive/planning/curve-sampler-research-plan.md) — Curve sampler — preregistered research plan (distinctness track)
-- [planning/journal.md](../docs/archive/planning/journal.md) — Engineering Journal
-- [planning/memory-docs-and-dag-plan.md](../docs/archive/planning/memory-docs-and-dag-plan.md) — Memory docs organization + DAG-view refresh — review & plan
-- [planning/pi-integration-review.md](../docs/archive/planning/pi-integration-review.md) — pi integration review — internal embeds + `harness pi` (2026-07-01)
-- [planning/release-notes-v0.0.10.md](../docs/archive/planning/release-notes-v0.0.10.md) — mlx-bun v0.0.10 — batching parity, SSD KV cache, sharper serving
-- [planning/release-notes-v0.0.11.md](../docs/archive/planning/release-notes-v0.0.11.md) — v0.0.11 release notes
-- [planning/release-notes-v0.0.12.md](../docs/archive/planning/release-notes-v0.0.12.md) — v0.0.12 release notes
-- [planning/release-notes-v0.0.13.md](../docs/archive/planning/release-notes-v0.0.13.md) — v0.0.13 release notes
-- [planning/release-notes-v0.0.9.md](../docs/archive/planning/release-notes-v0.0.9.md) — v0.0.9 release notes (DRAFT — Josh edits + publishes)
-- [planning/release-notes-v0.2.0.md](../docs/archive/planning/release-notes-v0.2.0.md) — mlx-bun v0.2.0
-- [planning/release-notes-v0.3.0.md](../docs/archive/planning/release-notes-v0.3.0.md) — mlx-bun v0.3.0
-- [planning/release-notes-v0.4.0.md](../docs/archive/planning/release-notes-v0.4.0.md) — mlx-bun v0.4.0
-- [planning/release-notes-v0.5.0.md](../docs/archive/planning/release-notes-v0.5.0.md) — mlx-bun v0.5.0
-- [planning/web-ui-pass-plan.md](../docs/archive/planning/web-ui-pass-plan.md) — Web UI pass — ranked fix list (2026-07-01 audit)
-- [planning/website-readme-pass-plan.md](../docs/archive/planning/website-readme-pass-plan.md) — Website + README pass — audit findings and fix plan (2026-07-01)

package/docs/archive/hlg-sampling.md

@@ -1,350 +0,0 @@
-# HLG sampling — a piecewise tone curve on the logits
-
-Status: **implemented, found neutral, superseded by Curve Designer** — `applyHlg` shipped in `src/sampler.ts`; investigation found HLG a wash vs plain temperature; the Curve Designer (`src/curve-sampler.ts`) is its v2 replacement. See [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md) for findings. This doc remains as the design rationale.
-Owner: sampling layer (`src/sampler.ts`)
-Default: **off** (`--hlg-sampling off` = today's temperature sampler, untouched)
-
-> This is the canonical **design/rationale** for HLG sampling. Live
-> **status/tracking** (checkboxes, findings) lives in PLAN.md under
-> "Phase 19 — HLG sampling". The user-facing flag/param reference lives in
-> [docs/reference/server-config.md](../reference/server-config.md) and
-> [docs/reference/server-api.md](../reference/server-api.md) once shipped.
-
-## Outcome / Retrospective
-
-HLG was implemented through **Piece 2** (pure curve + neutrality tests + serial wiring, `applyHlg` live in `src/sampler.ts`). Evaluation found it **neutral vs plain temperature** — no measurable gain in diversity or quality at matched output entropy. As a result, HLG is **superseded by the Curve Designer** (`src/curve-sampler.ts`), which generalizes the same region-shaping idea with an editable control-point interface and cleaner UX. Full empirical findings are in [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md).
-
-The sections below (Goal through Correctness) remain as design rationale. Pieces 3–6 of Phasing and the Open Questions were never executed; see the [Phasing](#phasing-the-piece-n-increments) and [Open Questions](#open-questions--risks) sections for historical context.
-
-## Goal
-
-Add a sampling transform — gated entirely behind `--hlg-sampling on` and a
-per-request `hlg` object — that replaces temperature's single global slope
-with a **pivoted, region-aware contrast curve** on the per-token
-log-probabilities.
-
-The move is a **cross-domain transplant**: take a mathematical structure that is
-standard in one field — a piecewise nonlinear transfer function — and apply it
-in one that has never used it. HLG (Hybrid Log-Gamma) is the structure we lift:
-where a plain gamma is one power curve, HLG is **piecewise**, shaping the low,
-middle, and high range of a signal under separate constraints. A logit
-distribution is another such signal. The hypothesis is that shaping its three
-regions independently buys something a single global temperature cannot — and
-that claim is settled by measurement in *this* domain, not by the structure's
-track record in its original one.
-
-This is a post-inference, **model-agnostic** transform — it operates on the
-logits vector after the forward pass, so it applies identically to every model
-(MiniCPM5 + the three Gemma-4 quants) and every lane (serial + `--batch N`)
-with **zero per-model code**. It is the first sampling feature in the project
-that has **no oracle ancestor** (neither mlx-lm nor optiq does this), so it is
-gated by KL + quality + diversity, not parity — with one exception that makes
-it safe to ship: see [Correctness](#correctness--evaluation).
-
-## Why temperature isn't enough (the thesis)
-
-Temperature scales every logit by the same factor: `logit / T`. In tone-curve
-terms it is a **single straight line through the origin** — one global slope.
-Lower `T` steepens it everywhere (sharper, more confident); higher `T` flattens
-it everywhere (more diverse).
-
-Its limitation is a **coupling**: the only way temperature loosens the model's
-grip on its top token is by raising `T`, which *simultaneously* lifts the tail.
-You cannot, with one slope, reduce top-token dominance **and** keep a soft floor
-under the tail. Raise the temperature to get novelty and you also import
-low-probability noise; lower it to suppress noise and you re-collapse onto the
-single most likely token. One number cannot move two regions independently.
-
-The fix is structural, not a better choice of `T`: make the slope **depend on
-the region of the distribution**. This is precisely what nonlinear transfer
-functions do in signal and color encoding — a single piecewise curve shapes the
-low, middle, and high range under separate constraints. The cross-domain idea
-here is to transplant that apparatus onto a logit distribution, which is just
-another value distribution. Mapped onto the three regions of a token
-distribution, the curve's response is:
-
-- **High-probability region** (the model's most confident tokens) →
-  **shoulder**: roll the slope off so the top values compress toward their
-  neighbours. The model stops being *so fixed* on its favourite answer.
-- **Mid-probability region** (where novelty and interest live) → **gain > 1**:
-  steepen the slope. The local-contrast boost separates the
-  plausible-and-interesting from the merely-mediocre.
-- **Low-probability tail** → **toe**: gently reduce the slope toward a soft
-  floor. Suppress the tail *smoothly* — unlike top-p/top-k, which hard-clip it
-  to `-inf`, and unlike high temperature, which inflates it.
-
-The payoff is the **decoupling** temperature cannot achieve: roll off the high
-end *and* hold a soft floor under the tail at the same time — a region of
-sampling behaviour no single-knob method reaches. Whether that decoupling is
-*useful* is an empirical question, settled in [Correctness](#correctness--evaluation),
-not by the pedigree of the curve.
-
-## The transfer function
-
-We operate in **log-probability space**, the natural "stops" axis for a
-probability distribution (the sampler already computes `toLogprobs`,
-[src/sampler.ts:127](../../src/sampler.ts)). Let `ℓ_i` be each token's log-prob
-and `μ` the pivot (middle grey — see [Pivot](#the-pivot--middle-grey)). Define
-the centered coordinate
-
-```
-z_i = ℓ_i − μ
-```
-
-and remap it with a **C¹ log-toe / linear-mid / log-shoulder** curve. The
-piecewise form is deliberate — it honours HLG's own breakpoints (HLG literally
-switches from a gamma segment to a log segment at E = 1/12):
-
-```
-        ⎧  −m·w − m·β_t·ln(1 + (−z − w)/β_t)     z < −w     (toe / shadows)
- g(z) = ⎨   m·z                                  |z| ≤ w    (gain / mids)
-        ⎩   m·w + m·β_h·ln(1 + ( z − w)/β_h)     z >  w     (shoulder / highlights)
-```
-
-The remapped logits are `ℓ'_i = g(z_i)`. The `+μ` constant shift cancels under
-softmax, so we drop it and feed `g(z_i)` straight to the existing
-`randomCategorical` draw.
-
-Properties that matter:
-
-- **Slope** is `m` at the pivot and decays as `m·β / (β + d)` a distance `d`
-  past each knot — continuous at the knots (C¹), monotone, and always positive.
-- **Monotone ⇒ ranking-preserving.** `g` never reorders tokens: it is a pure
-  contrast/tone operation, not a re-ranker. Pairwise orderings and the argmax
-  are invariant. (Tested — see [Correctness](#correctness--evaluation).)
-- **`-inf` safe.** A token masked by top-p/top-k (`ℓ_i = -inf`) lands in the toe
-  branch and maps to `-inf` — masking survives the remap, no NaN.
-
-### Knobs → what each controls
-
-| Param | Controls | Effect |
-| --- | --- | --- |
-| `pivot` μ | center of the curve | where the contrast boost is anchored in the distribution (see below) |
-| `gain` m | mid-region slope | `m > 1` sharpens mid-probability tokens; folds temperature (`m = 1/T`) |
-| `width` w | extent of the mid region | how many nats around the pivot count as "mids" |
-| `shoulder` β_h | high-prob rolloff | small = compresses the top tokens fast → top-token diversity |
-| `toe` β_t | low-prob rolloff | small = quick gentle fade of the tail; large = keep more tail |
-
-All knobs are in **nats** (the log-prob unit), so they are scale-free across
-models and contexts.
-
-### The degeneracies are the safety anchors
-
-The curve is a **strict generalization of temperature**, and that is what makes
-a no-oracle path safe to ship — the default and neutral paths reduce *exactly*
-to today's sampler:
-
-- `m = 1`, rolloff off (`w → ∞`, or `β → ∞`) ⟹ `g(z) = z` ⟹ **bit-exact the
-  current sampler at T = 1**.
-- rolloff off (`w → ∞`), any `m` ⟹ `g(z) = m·z` ⟹ **bit-exact temperature
-  `T = 1/m`** (the existing `mulScalar(cur, 1/temperature)` step).
-
-So there is a configuration in which HLG is provably identical to temperature,
-down to the bit. That is the parity-equivalent gate (below).
-
-### Greedy is untouched
-
-Under greedy decoding (`temperature === 0`) the sampler returns `argmax`
-([src/sampler.ts:78](../../src/sampler.ts)). Because `g` is monotone it cannot
-change the argmax, so **HLG is a no-op at temperature 0 by construction** and is
-only engaged for `temperature > 0`. The greedy parity gate is therefore
-trivially preserved.
-
-## The pivot
-
-Choosing the pivot is the genuinely interesting part: the curve's center has to
-mean something across distributions as different as a near-deterministic next
-token and a wide-open one. Three modes, all cheap, exposed as `pivot_mode`
-(default **top-anchored**). The other two ship as documented opt-in modes —
-losing experiments become flags, never deletions.
-
-The pivot is computed from the **full, normalized log-prob vector before any
-top-p/top-k masking**, so masked `-inf` entries never contaminate it.
-
-1. **`top` — top-anchored (DEFAULT).** `μ = ℓ_max − c`. The curve centers `c`
-   nats below the most-probable token. Predictable, scale-free, one `max`
-   reduction. `c` is the meaningful knob; default calibration-pending (Piece 5
-   sweep).
-2. **`entropy` — entropy-anchored.** `μ = Σ p_i ℓ_i = −H`, the distribution's
-   center of mass in tonal space. Auto-exposure: confident contexts (low
-   entropy) pull the pivot up near the top; flat contexts push it down. One
-   dot-product, information-theoretically natural, less predictable.
-3. **`median` — mass-median.** `μ` = the log-prob at the 50% cumulative-mass
-   boundary (literal auto-levels / histogram median). Most adaptive; reuses the
-   sort top-p already performs.
-
-`width` may likewise be a fixed nat value or, in a later increment, auto-derived
-from the log-prob spread (an "auto-contrast" mode). Default fixed for now.
-
-## Temperature semantics
-
-When `hlg` is active, the request's `temperature` **folds into the mid gain**:
-`m = 1 / T`. Temperature *is* the mid-tone contrast, and HLG adds the toe and
-shoulder on top of it. This avoids double-applying a slope and preserves the
-intuition that "temperature" still means "how punchy the mids are." With
-rolloff off, `m = 1/T` and `g(z) = z/T` — exactly temperature, as above.
-
-## Where it lands in the code
-
-Sampling is fully model-agnostic and shared by every model and lane
-([src/sampler.ts](../../src/sampler.ts), post-inference), so this is a single
-transform with no per-model branches.
-
-- **The transform** — a new `applyHlg(lp, params)` in
-  [src/sampler.ts](../../src/sampler.ts). HLG is a **replacement sampler**:
-  `makeSampler` branches `if (hlg.enabled)` → the curve is the *whole*
-  post-logits step (its toe does the tail control), `else` → exactly what we
-  used to do (top-p, top-k, then `mulScalar(cur, 1/temperature)`). The two are
-  mutually exclusive — when HLG is on, top-p/top-k are **not** applied, because
-  the smooth toe is their replacement, not a layer on top of them. Branchless:
-  compute the toe / mid / shoulder expressions and select on `z` vs `±w` with
-  `where`. Follows the file's strict `owned[]` → `dispose()` discipline (every
-  intermediate freed; only the chosen token id crosses to JS).
-- **Sampler options** — extend `SamplerOptions`
-  ([src/sampler.ts:11](../../src/sampler.ts)) with an optional `hlg` sub-object;
-  `makeSampler` builds the HLG step when present, else the existing path
-  verbatim.
-
-Three sampler **construction** sites pass the params through; the
-degeneracy guarantees keep every existing parity gate green:
-
-- **Serial** — `makeSampler(options)` in
-  [src/generate.ts:218](../../src/generate.ts).
-- **Batched per-row** — `makeSampler(options)` in
-  [src/serve/generation-gateway.ts:127](../../src/serve/generation-gateway.ts).
-  Each row already owns its sampler closure, so `hlg` params batch per-request
-  for free; the draw site in
-  [src/serve/batch-scheduler.ts:276](../../src/serve/batch-scheduler.ts) is
-  unchanged beyond construction.
-
-### MLX op feasibility
-
-All elementwise: `exp`, `sub`, `mul`/`mulScalar`, `where`, plus `log` / `log1p`.
-The pivot needs one `max` (top), one dot-product (entropy), or the existing sort
-(median). Cost is O(V) per token — the same order as the existing top-p step,
-negligible against the forward pass, but measured (Piece 5). If `mlx_log1p`
-isn't already bound, bind it from the header first — read the full signature to
-avoid the trailing-stream-arg footgun (CLAUDE.md).
-
-## Flag, config, and API surface
-
-Conventions per [docs/reference/server-config.md](../reference/server-config.md)
-and `serverRuntimeFlags()` ([src/cli.ts](../../src/cli.ts)).
-
-- **CLI**: `--hlg-sampling on|off` (default **off**), plus `--hlg-width`,
-  `--hlg-shoulder`, `--hlg-toe`, and the top-anchor offset `--hlg-pivot-offset`
-  (the `c` above). There is **no `--hlg-gain`**: the mid gain folds from
-  `--temperature` (`m = 1/T`), so temperature stays the one contrast knob and a
-  second one would be redundant. `--hlg-pivot top|entropy|median` arrives with
-  the alternate pivot modes in Piece 4 (top-anchored is the only mode until
-  then). Parsed with the existing `onOff` / `numFlag` helpers; validated (exit
-  on bad value); defaults onto `ServerOptions`.
-- **ServerOptions** ([src/server.ts](../../src/server.ts)): an `hlg?` config
-  object, resolved in `toOptions` with the standard precedence
-  (request > CLI default > model config > built-in), exactly like the existing
-  sampling defaults.
-- **Per-request**: an `hlg` object on `ChatRequest` (unknown fields are already
-  tolerated), so it works over OpenAI `/v1/chat/completions`, Anthropic
-  `/v1/messages`, and `/v1/responses` with no protocol-specific plumbing.
-  Example:
-  ```jsonc
-  {
-    "temperature": 0.7,            // becomes the mid gain m = 1/T
-    "hlg": {
-      "enabled": true,
-      "pivot": "top", "pivot_offset": 6.0,
-      "width": 4.0, "shoulder": 4.0, "toe": 6.0
-    }
-  }
-  ```
-
-## Correctness & evaluation
-
-This is a novel path with **no oracle ancestor**, so it is gated by KL +
-quality + diversity rather than parity — except for the degeneracy gates, which
-*are* parity gates and must be bit-exact.
-
-1. **Neutrality gate (bit-exact)** — `tests/hlg-sampling-parity.test.ts`:
-   - flag-off ⟹ the sampler code path is byte-identical to today's (`makeSampler`
-     unchanged when `hlg` absent);
-   - `hlg` in *identity config* (`gain = 1`, rolloff off) reduces to the current
-     sampler with `maxDiff === 0`;
-   - `hlg` rolloff-off, `gain = 1/T` reduces to temperature `T` bit-exact.
-   Run across **all four models** and **both lanes** (serial + batched) — the
-   param plumbing differs per lane, the math does not.
-2. **Monotonicity / ranking preservation** — property test over random logits:
-   `g` never reorders tokens; argmax invariant; every pairwise ordering held.
-3. **KL characterization** — reuse [src/eval/kl.ts](../../src/eval/kl.ts)
-   `evaluateKlSelfFlag` (env lever off vs on) to *characterize* (not pass/fail)
-   how far each knob moves the distribution from temperature-only. Output: a
-   KL-vs-knob curve per model, recorded for the design log. The distribution is
-   *supposed* to move; the point is to map the knob space, not to bound drift.
-4. **Capability guardrail** — `bun scripts/eval.ts capability --candidate e4b`
-   (and 12B, the reference target) with HLG on vs off. The six tasks
-   (GSM8K / MMLU / IFEval / BFCL / HumanEval / HashHop) are accuracy-shaped, so
-   they measure the **cost**: does shaping the distribution break reasoning or
-   tool-calling? That is the guardrail HLG must not regress materially.
-5. **Diversity lens (the benefit)** — the six tasks won't show the upside, since
-   the whole point is mid-tone novelty. Add a small open-ended eval
-   (`src/eval/tasks/diversity.ts`): distinct-n / self-BLEU / cross-sample
-   entropy on a creative-prompt set, **HLG vs temperature matched to the same
-   output entropy**. The thesis is confirmed iff, at equal entropy, HLG yields
-   higher diversity without the tail-garbage temperature would import.
-6. **Perf A/B** — a `bench-compat-vs-perf`-style env-lever A/B plus a
-   `./benchmark.sh` row: decode tok/s + TTFT, on vs off, to show ~0 decode
-   regression. Lands in [benchmarks/RESULTS.md](../../benchmarks/RESULTS.md) §3.
-
-## Phasing (the "piece N" increments)
-
-> **Historical / superseded.** Pieces 1–2 shipped. Pieces 3–6 were never executed — HLG was evaluated after Piece 2 and found neutral; the feature was superseded by the Curve Designer before Piece 3 began.
-
-1. **Pure curve + neutrality tests** — `applyHlg(lp, params)` in `sampler.ts`,
-   top-anchored pivot only; degeneracy + monotonicity tests green across all
-   four models. (No flag wired yet — pure, fully-tested function.)
-2. **Serial wiring** — CLI flags + `ServerOptions` + `toOptions`; live on the
-   serial server; per-request `hlg`.
-3. **Batched wiring** — gateway/scheduler sampler construction; batched
-   neutrality test.
-4. **Pivot modes 2 & 3** — entropy + median, behind `--hlg-pivot`.
-5. **Eval + benchmark** — KL characterization, capability guardrail, diversity
-   lens, perf A/B; set shipped defaults from the sweep; RESULTS.md row.
-6. **Docs** — finalize this doc, the investigation write-up, PLAN/STATUS,
-   server-config / server-api / README, and a memory note.
-
-## Open questions / risks
-
-> **Historical / superseded.** These questions were open at the time of design. HLG evaluation concluded with a neutral verdict before they were answered; the Curve Designer supersedes this path. Questions are preserved as design context.
-
-- **Default knob values** are calibration-pending — set empirically by the
-  Piece 5 sweep, not guessed. Initial exploration points: `c ≈ 6`, `w ≈ 4`,
-  `β_h ≈ 4`, `β_t ≈ 6` nats; confirm or replace with measured values.
-- **Pivot for very low-entropy distributions** (one token ~1.0): the curve has
-  almost nothing to shape; verify it degrades gracefully to "near-greedy" rather
-  than amplifying numerical noise in the tail.
-- **HLG replaces top-p/top-k** (resolved, not a rail). When HLG is on it *is*
-  the sampler — no top-p/top-k underneath; the toe is the smooth cousin of
-  min-p and does the tail control. Open question is whether the soft toe
-  suppresses the tail *enough* on a 262k vocab to match the hard cutoffs, or
-  whether garbage leaks — exactly what the `hlg-compare` harness probes.
-- **Does the benefit survive the capability tasks?** If HLG measurably helps
-  diversity but dents GSM8K/BFCL, it ships default-off with a documented
-  use-case (creative/open-ended), not as a global default — consistent with the
-  project's default-off-flags ethos.
-
-## Provenance — and why the source domain doesn't justify it
-
-This is a **cross-domain transplant**. Nonlinear transfer functions are a mature
-apparatus in signal and color encoding for reshaping a value distribution under
-region-dependent constraints; a logit distribution is just another value
-distribution, so the apparatus carries over. HLG (Hybrid Log-Gamma, ARIB
-STD-B67 / ITU-R BT.2100) is the specific structure we lift — a gamma segment for
-the lower range and a logarithmic segment for the upper range, joined at a
-breakpoint — because its piecewise shape maps cleanly onto "boost the mids, roll
-off the extremes."
-
-The provenance is where the *structure* comes from; it is **not** the argument
-for it. That a transfer function is standard practice in another domain says
-nothing about whether it helps token sampling — that is decided only by
-measurement (the KL characterization, the capability guardrail, and the
-diversity lens in [Correctness](#correctness--evaluation)). The full empirical
-write-up is in [docs/archive/investigations/hlg-sampling-investigation.md](investigations/hlg-sampling-investigation.md).