wiki-plugin-similarity 0.8.1 → 0.9.0

package/client/similarity.js

@@ -1,4 +1,4 @@
-/* wiki-plugin-similarity - 0.8.1 - Tue, 21 Jul 2026 08:15:59 GMT */
+/* wiki-plugin-similarity - 0.9.0 - Wed, 22 Jul 2026 07:41:00 GMT */
 (()=>{var q={high:.78,medium:.68,low:.58},M=q.medium,_=10,V=t=>{let e=[],n=[],o=[],f=null,b=null,d="search",y=!1,L=!1,E=null,k=null,w=(i,m)=>i===m||i.startsWith(m)&&/^[\s:]/.test(i.slice(m.length)),x=(i,m)=>i.slice(m.length).replace(/^\s*:?\s*/,"").trim();for(let i of t.split(`
 `)){let m=i.trim();if(!m||m.startsWith("#"))continue;let g=m.toUpperCase();if(w(g,"LIVE")){y=!0;continue}if(w(g,"AUTHOR")){!e.length&&d==="search"&&(d="author");continue}if(w(g,"REPORT")){d==="search"&&(d="report");continue}if(w(g,"KEYWORD")){d==="search"&&(d="keyword");continue}if(w(g,"BUILD")){d==="search"&&(d="build");continue}if(w(g,"FORCE")){L=!0;continue}if(w(g,"GHOST")){E=x(m,"GHOST"),d==="search"&&(d="ghost");continue}if(w(g,"BUTTON")){k=x(m,"BUTTON");continue}if(w(g,"ROSTER")){let S=x(m,"ROSTER");S&&n.push(S);continue}if(w(g,"FARM")){let S=x(m,"FARM");S&&o.push(S);continue}if(w(g,"LIST")){!e.length&&d==="search"&&(d="list");continue}if(w(g,"SIMILAR")){let S=x(g,"SIMILAR").toLowerCase();f=q[S]||M,!e.length&&d==="search"&&(d="similar");continue}if(w(g,"THRESHOLD")){let S=x(m,"THRESHOLD");f=q[S.toLowerCase()]??(parseFloat(S)||M);continue}if(w(g,"LIMIT")){b=parseInt(x(m,"LIMIT"))||_;continue}e.push(["PUBLIC","LOCAL","PRIVATE"].includes(g)?g:m)}return{mode:d,specs:e,rosterRefs:n,farms:o,threshold:f??M,limit:b??_,live:y,force:L,ghostUrl:E,label:k,thresholdSet:f!==null}},et=t=>t.includes("*")||t.includes("?"),nt=t=>t==="PUBLIC"||t==="LOCAL"||t==="PRIVATE",st=t=>t.toLowerCase().replace(/\s+/g,"-").replace(/[^a-z0-9-]/g,""),P=new Map,it=async(t,e)=>{if(P.has(t))return P.get(t);let n=`${e}/system/indexed-domains.json?pattern=${encodeURIComponent(t)}`,o=await fetch(n);if(!o.ok)throw new Error(`indexed-domains failed: ${o.status}`);let f=await o.json();return P.set(t,f),f},G=async(t,e)=>{t.length||(t=[window.location.hostname]);let n=new Set,o=[];for(let f of t)if(f==="*"||et(f)||nt(f))for(let b of await it(f,e))n.has(b.domain)||(n.add(b.domain),o.push(b));else n.has(f)||(n.add(f),o.push({domain:f,page_count:null}));return o},ot=/^([a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+|localhost)(:\d+)?$/,at=/^ROSTER ([A-Za-z0-9.\-:]+\/[a-z0-9-]+)$/,rt=/^REFERENCES ([A-Za-z0-9.\-:]+\/[a-z0-9-]+)$/,B=async t=>{let e=t.indexOf("/"),n=await fetch(`//${t.slice(0,e)}/${t.slice(e+1)}.json`);if(!n.ok)throw new Error(`roster page ${t} failed: ${n.status}`);return n.json()},K=async(t,e,n)=>{if(n.has(t))return;n.add(t);let o;try{o=await B(t)}catch(f){console.warn(f.message);return}for(let f of o.story||[])if(f.type==="roster")for(let b of(f.text||"").split(/\r?\n/)){let d=b.trim();if(!d)continue;let y=d.match(ot);if(y){e.add(y[0]);continue}let L=d.match(at);if(L){await K(L[1],e,n);continue}let E=d.match(rt);if(E)try{let k=await B(E[1]);for(let w of k.story||[])w.type==="reference"&&w.site&&e.add(w.site)}catch(k){console.warn(k.message)}}},lt=async t=>{let e=new Set,n=new Set;for(let o of t)await K(o,e,n);return[...e]},ct=async(t,e)=>e.length?[...t,...await lt(e)]:t,A=new Map,dt=t=>`${window.location.origin}/system/semantic-vectors.json?domain=${encodeURIComponent(t)}`,Z=async t=>{if(A.has(t))return A.get(t);let e=await fetch(dt(t));if(!e.ok)return[];let n=await e.json();return A.set(t,n),n},z=async(t,e)=>{let n=await fetch(`${e}/system/embed.json?text=${encodeURIComponent(t)}`);if(!n.ok)throw new Error(`embed failed: ${n.status}`);return(await n.json()).vector},ft=async(t,e)=>{let o=(await Z(e)).find(f=>f.slug===t);return o?o.vector:null},H=(t,e,{threshold:n,limit:o,excludeSlug:f,excludeDomain:b})=>{let d=[];for(let{domain:y,pages:L}of e)for(let{slug:E,title:k,vector:w}of L){if(E===f&&y===b)continue;let x=0;for(let i=0;i<t.length;i++)x+=t[i]*w[i];x>=n&&d.push({domain:y,slug:E,title:k,score:x})}return d.sort((y,L)=>L.score-y.score),d.slice(0,o)},F=async(t,e)=>{let n=await G(t,e);return(await Promise.all(n.map(async({domain:f})=>({domain:f,pages:await Z(f)})))).filter(f=>f.pages.length>0)},J=t=>`sim-cache-${t}`,mt=t=>{try{let e=JSON.parse(localStorage.getItem(J(t.id))||"null");return e?.text===(t.text||"")?e:null}catch{return null}},O=(t,e)=>{try{localStorage.setItem(J(t.id),JSON.stringify({text:t.text||"",ts:Date.now(),...e}))}catch{}},ut=t=>{let e=Math.floor((Date.now()-t)/1e3);return e<60?`${e}s ago`:e<3600?`${Math.floor(e/60)}m ago`:e<86400?`${Math.floor(e/3600)}h ago`:`${Math.floor(e/86400)}d ago`},I=`
   .sim-form { display:flex; gap:6px; margin-bottom:8px; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-plugin-similarity",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Federated Wiki plugin \u2014 semantic similarity search across wiki domains using prebuilt vector indexes",
   "keywords": [
     "wiki",

package/pages/about-similarity-plugin

@@ -4,12 +4,12 @@
     {
       "type": "markdown",
       "id": "aec1dfcd5f2bc42b",
-      "text": "The Similarity plugin adds search to a Federated Wiki farm — semantic similarity over prebuilt vector indexes, ranked search reports, and galactic keyword search over each site's own MiniSearch index. One item type — **similarity** — with a line-oriented DSL, plus a server component that serves every search same-origin. Works on any host: embedding runs in-process (native ONNX where available, WASM everywhere else)."
+      "text": "The Similarity plugin adds search to a Federated Wiki farm \u2014 semantic similarity over prebuilt vector indexes, ranked search reports, and galactic keyword search over each site's own MiniSearch index. One item type \u2014 **similarity** \u2014 with a line-oriented DSL, plus a server component that serves every search same-origin. Works on any host: embedding runs in-process (native ONNX where available, WASM everywhere else)."
     },
     {
       "type": "markdown",
       "id": "28edff984cc5334d",
-      "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) — interactive semantic search form\n- `SIMILAR: high|medium|low` — ambient: pages similar to this page\n- `REPORT` — server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` — galactic MiniSearch over live site-index.json files\n- `LIST` — table of indexed domains\n- `AUTHOR` — search results as a draggable ghost page\n- `BUILD` / `FORCE` — proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` — open any page-json as a ghost page\n- `ROSTER site/slug` — add a roster page's sites to the scope (off-farm sites searched via the galaxy cache)\n- `FARM domain` — ask a peer farm to continue the search. The peer answers from exactly the sites whose own [[Federated Farm Search]] page grants your origin (`FROM` lines; `FROM *` needs the peer admin's `WIKI_PEER_FEDERATION=open`)\n- `THRESHOLD: 0.72` · `LIMIT: 8` · `LIVE` — tuning"
+      "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) \u2014 interactive semantic search form\n- `SIMILAR: high|medium|low` \u2014 ambient: pages similar to this page\n- `REPORT` \u2014 server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` \u2014 galactic MiniSearch over live site-index.json files\n- `LIST` \u2014 table of indexed domains\n- `AUTHOR` \u2014 search results as a draggable ghost page\n- `BUILD` / `FORCE` \u2014 proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` \u2014 open any page-json as a ghost page\n- `ROSTER site/slug` \u2014 add a roster page's sites to the scope (off-farm sites searched via the galaxy cache)\n- `FARM domain` \u2014 ask a peer farm to continue the search. The peer answers from exactly the sites whose own [[Federated Farm Search]] page grants your origin (`FROM` lines; `FROM *` needs the peer admin's `WIKI_PEER_FEDERATION=open`)\n- `THRESHOLD: 0.72` \u00b7 `LIMIT: 8` \u00b7 `LIVE` \u2014 tuning"
     },
     {
       "type": "markdown",
@@ -54,12 +54,12 @@
     {
       "type": "markdown",
       "id": "d9a96dfebb9d1692",
-      "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` — keyword search over off-farm federation sites\n- `GET /system/peer-hello.json` — capability probe: version, model, federation status (404 = plugin absent)\n- `POST /system/peer-search.json` — answer another farm's search. Two keys: the admin's `WIKI_PEER_FEDERATION` ceiling (off / grants / open) and each site's Federated Farm Search grants page; scope = union of granting sites; hop limit, replay dedup, IP-keyed + global rate limits; restricted sites always excluded\n\nIndexes are `status/semantic-vectors.json` per domain — built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised — byte-compatible with the index builder."
+      "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` \u2014 keyword search over off-farm federation sites\n- `GET /system/peer-hello.json` \u2014 capability probe: version, model, federation status (404 = plugin absent)\n- `GET /system/similarity-health.json` \u2014 embedder supervisor state: child-process / semindex / url, breaker status, recent crashes\n- `POST /system/peer-search.json` \u2014 answer another farm's search. Two keys: the admin's `WIKI_PEER_FEDERATION` ceiling (off / grants / open) and each site's Federated Farm Search grants page; scope = union of granting sites; hop limit, replay dedup, IP-keyed + global rate limits; restricted sites always excluded\n\nIndexes are `status/semantic-vectors.json` per domain \u2014 built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised \u2014 byte-compatible with the index builder.\n\nSince 0.9.0 all query embedding runs in a supervised child process, never in the wiki server itself: a crash in the ONNX runtime fails that one search, and repeated crashes trip a circuit breaker that answers 503 while cooling down. The worst case for a wiki running this plugin is \"semantic search temporarily unavailable\" \u2014 never a dead wiki."
     },
     {
       "type": "markdown",
       "id": "21eb5354d2adb29e",
-      "text": "**Version:** 0.7.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] — architecture, indexing, freshness."
+      "text": "**Version:** 0.9.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] \u2014 architecture, indexing, freshness."
     }
   ],
   "plugin": "similarity",
@@ -72,12 +72,12 @@
           {
             "type": "markdown",
             "id": "aec1dfcd5f2bc42b",
-            "text": "The Similarity plugin adds search to a Federated Wiki farm — semantic similarity over prebuilt vector indexes, ranked search reports, and galactic keyword search over each site's own MiniSearch index. One item type — **similarity** — with a line-oriented DSL, plus a server component that serves every search same-origin. Works on any host: embedding runs in-process (native ONNX where available, WASM everywhere else)."
+            "text": "The Similarity plugin adds search to a Federated Wiki farm \u2014 semantic similarity over prebuilt vector indexes, ranked search reports, and galactic keyword search over each site's own MiniSearch index. One item type \u2014 **similarity** \u2014 with a line-oriented DSL, plus a server component that serves every search same-origin. Works on any host: embedding runs in-process (native ONNX where available, WASM everywhere else)."
           },
           {
             "type": "markdown",
             "id": "28edff984cc5334d",
-            "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) — interactive semantic search form\n- `SIMILAR: high|medium|low` — ambient: pages similar to this page\n- `REPORT` — server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` — galactic MiniSearch over live site-index.json files\n- `LIST` — table of indexed domains\n- `AUTHOR` — search results as a draggable ghost page\n- `BUILD` / `FORCE` — proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` — open any page-json as a ghost page\n- `THRESHOLD: 0.72` · `LIMIT: 8` · `LIVE` — tuning"
+            "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) \u2014 interactive semantic search form\n- `SIMILAR: high|medium|low` \u2014 ambient: pages similar to this page\n- `REPORT` \u2014 server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` \u2014 galactic MiniSearch over live site-index.json files\n- `LIST` \u2014 table of indexed domains\n- `AUTHOR` \u2014 search results as a draggable ghost page\n- `BUILD` / `FORCE` \u2014 proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` \u2014 open any page-json as a ghost page\n- `THRESHOLD: 0.72` \u00b7 `LIMIT: 8` \u00b7 `LIVE` \u2014 tuning"
           },
           {
             "type": "markdown",
@@ -122,17 +122,17 @@
           {
             "type": "markdown",
             "id": "d9a96dfebb9d1692",
-            "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n\nIndexes are `status/semantic-vectors.json` per domain — built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised — byte-compatible with the index builder."
+            "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n\nIndexes are `status/semantic-vectors.json` per domain \u2014 built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised \u2014 byte-compatible with the index builder."
           },
           {
             "type": "markdown",
             "id": "21eb5354d2adb29e",
-            "text": "**Version:** 0.5.1\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] — architecture, indexing, freshness."
+            "text": "**Version:** 0.5.1\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] \u2014 architecture, indexing, freshness."
           }
         ]
       },
       "date": 1783782734556,
-      "provenance": "Authored by an AI agent — Claude Fable 5 via the [[fedwiki-page]] skill. [https://claude.com/claude-code Claude Code]"
+      "provenance": "Authored by an AI agent \u2014 Claude Fable 5 via the [[fedwiki-page]] skill. [https://claude.com/claude-code Claude Code]"
     },
     {
       "type": "edit",
@@ -140,7 +140,7 @@
       "item": {
         "type": "markdown",
         "id": "28edff984cc5334d",
-        "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) — interactive semantic search form\n- `SIMILAR: high|medium|low` — ambient: pages similar to this page\n- `REPORT` — server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` — galactic MiniSearch over live site-index.json files\n- `LIST` — table of indexed domains\n- `AUTHOR` — search results as a draggable ghost page\n- `BUILD` / `FORCE` — proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` — open any page-json as a ghost page\n- `ROSTER site/slug` — add a roster page's sites to the scope (off-farm sites searched via the galaxy cache)\n- `FARM domain` — ask a peer farm to continue the search (experimental; requires the peer's `search-peers` roster to allow you)\n- `THRESHOLD: 0.72` · `LIMIT: 8` · `LIVE` — tuning"
+        "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) \u2014 interactive semantic search form\n- `SIMILAR: high|medium|low` \u2014 ambient: pages similar to this page\n- `REPORT` \u2014 server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` \u2014 galactic MiniSearch over live site-index.json files\n- `LIST` \u2014 table of indexed domains\n- `AUTHOR` \u2014 search results as a draggable ghost page\n- `BUILD` / `FORCE` \u2014 proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` \u2014 open any page-json as a ghost page\n- `ROSTER site/slug` \u2014 add a roster page's sites to the scope (off-farm sites searched via the galaxy cache)\n- `FARM domain` \u2014 ask a peer farm to continue the search (experimental; requires the peer's `search-peers` roster to allow you)\n- `THRESHOLD: 0.72` \u00b7 `LIMIT: 8` \u00b7 `LIVE` \u2014 tuning"
       },
       "date": 1783800718188
     },
@@ -150,7 +150,7 @@
       "item": {
         "type": "markdown",
         "id": "d9a96dfebb9d1692",
-        "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` — keyword search over off-farm federation sites\n- `POST /system/peer-search.json` — answer another farm's search (guarded: allowlist roster, hop limit, replay dedup, rate limit; restricted sites always excluded)\n\nIndexes are `status/semantic-vectors.json` per domain — built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised — byte-compatible with the index builder."
+        "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` \u2014 keyword search over off-farm federation sites\n- `POST /system/peer-search.json` \u2014 answer another farm's search (guarded: allowlist roster, hop limit, replay dedup, rate limit; restricted sites always excluded)\n\nIndexes are `status/semantic-vectors.json` per domain \u2014 built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised \u2014 byte-compatible with the index builder."
       },
       "date": 1783800718188
     },
@@ -160,7 +160,7 @@
       "item": {
         "type": "markdown",
         "id": "21eb5354d2adb29e",
-        "text": "**Version:** 0.6.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] — architecture, indexing, freshness."
+        "text": "**Version:** 0.6.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] \u2014 architecture, indexing, freshness."
       },
       "date": 1783800718188
     },
@@ -170,7 +170,7 @@
       "item": {
         "type": "markdown",
         "id": "28edff984cc5334d",
-        "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) — interactive semantic search form\n- `SIMILAR: high|medium|low` — ambient: pages similar to this page\n- `REPORT` — server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` — galactic MiniSearch over live site-index.json files\n- `LIST` — table of indexed domains\n- `AUTHOR` — search results as a draggable ghost page\n- `BUILD` / `FORCE` — proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` — open any page-json as a ghost page\n- `ROSTER site/slug` — add a roster page's sites to the scope (off-farm sites searched via the galaxy cache)\n- `FARM domain` — ask a peer farm to continue the search. The peer answers from exactly the sites whose own [[Federated Farm Search]] page grants your origin (`FROM` lines; `FROM *` needs the peer admin's `WIKI_PEER_FEDERATION=open`)\n- `THRESHOLD: 0.72` · `LIMIT: 8` · `LIVE` — tuning"
+        "text": "## The DSL\n\nThe first ALL-CAPS keyword sets the mode; other lines are domain specs (globs, explicit domains, or the scope keywords PUBLIC / LOCAL / PRIVATE):\n\n- (no keyword) \u2014 interactive semantic search form\n- `SIMILAR: high|medium|low` \u2014 ambient: pages similar to this page\n- `REPORT` \u2014 server-side ranked, stub-filtered, fork-bundled report\n- `KEYWORD` \u2014 galactic MiniSearch over live site-index.json files\n- `LIST` \u2014 table of indexed domains\n- `AUTHOR` \u2014 search results as a draggable ghost page\n- `BUILD` / `FORCE` \u2014 proxy to the farm indexer, where configured\n- `GHOST url` / `BUTTON label` \u2014 open any page-json as a ghost page\n- `ROSTER site/slug` \u2014 add a roster page's sites to the scope (off-farm sites searched via the galaxy cache)\n- `FARM domain` \u2014 ask a peer farm to continue the search. The peer answers from exactly the sites whose own [[Federated Farm Search]] page grants your origin (`FROM` lines; `FROM *` needs the peer admin's `WIKI_PEER_FEDERATION=open`)\n- `THRESHOLD: 0.72` \u00b7 `LIMIT: 8` \u00b7 `LIVE` \u2014 tuning"
       },
       "date": 1784591495272
     },
@@ -180,7 +180,7 @@
       "item": {
         "type": "markdown",
         "id": "d9a96dfebb9d1692",
-        "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` — keyword search over off-farm federation sites\n- `GET /system/peer-hello.json` — capability probe: version, model, federation status (404 = plugin absent)\n- `POST /system/peer-search.json` — answer another farm's search. Two keys: the admin's `WIKI_PEER_FEDERATION` ceiling (off / grants / open) and each site's Federated Farm Search grants page; scope = union of granting sites; hop limit, replay dedup, IP-keyed + global rate limits; restricted sites always excluded\n\nIndexes are `status/semantic-vectors.json` per domain — built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised — byte-compatible with the index builder."
+        "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` \u2014 keyword search over off-farm federation sites\n- `GET /system/peer-hello.json` \u2014 capability probe: version, model, federation status (404 = plugin absent)\n- `POST /system/peer-search.json` \u2014 answer another farm's search. Two keys: the admin's `WIKI_PEER_FEDERATION` ceiling (off / grants / open) and each site's Federated Farm Search grants page; scope = union of granting sites; hop limit, replay dedup, IP-keyed + global rate limits; restricted sites always excluded\n\nIndexes are `status/semantic-vectors.json` per domain \u2014 built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised \u2014 byte-compatible with the index builder."
       },
       "date": 1784591495272
     },
@@ -190,9 +190,29 @@
       "item": {
         "type": "markdown",
         "id": "21eb5354d2adb29e",
-        "text": "**Version:** 0.7.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] — architecture, indexing, freshness."
+        "text": "**Version:** 0.7.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] \u2014 architecture, indexing, freshness."
       },
       "date": 1784591495272
+    },
+    {
+      "type": "edit",
+      "id": "d9a96dfebb9d1692",
+      "item": {
+        "type": "markdown",
+        "id": "d9a96dfebb9d1692",
+        "text": "## Server Routes\n\nAll same-origin, registered by the plugin's server component:\n\n- `GET /system/indexed-domains.json?pattern=`\n- `GET /system/semantic-vectors.json?domain=`\n- `GET /system/embed.json?text=`\n- `POST /system/search-report.json`\n- `GET /system/farm-search.json?q=&pattern=&limit=`\n- `GET /system/build-index.json?domains=` (proxied to the farm indexer)\n- `GET /system/galaxy-search.json?q=&sites=` \u2014 keyword search over off-farm federation sites\n- `GET /system/peer-hello.json` \u2014 capability probe: version, model, federation status (404 = plugin absent)\n- `GET /system/similarity-health.json` \u2014 embedder supervisor state: child-process / semindex / url, breaker status, recent crashes\n- `POST /system/peer-search.json` \u2014 answer another farm's search. Two keys: the admin's `WIKI_PEER_FEDERATION` ceiling (off / grants / open) and each site's Federated Farm Search grants page; scope = union of granting sites; hop limit, replay dedup, IP-keyed + global rate limits; restricted sites always excluded\n\nIndexes are `status/semantic-vectors.json` per domain \u2014 built by the farm indexer, distributed by sync, read from farm disk. Keyword search reads each site's per-edit `status/site-index.json`; no separate index is built. Query embedding is BAAI bge-small-en-v1.5, 384-dim, CLS-pooled, unit-normalised \u2014 byte-compatible with the index builder.\n\nSince 0.9.0 all query embedding runs in a supervised child process, never in the wiki server itself: a crash in the ONNX runtime fails that one search, and repeated crashes trip a circuit breaker that answers 503 while cooling down. The worst case for a wiki running this plugin is \"semantic search temporarily unavailable\" \u2014 never a dead wiki."
+      },
+      "date": 1784706029671
+    },
+    {
+      "type": "edit",
+      "id": "21eb5354d2adb29e",
+      "item": {
+        "type": "markdown",
+        "id": "21eb5354d2adb29e",
+        "text": "**Version:** 0.9.0\n\n# Links\n\n- [https://github.com/Hitchhikers-Guide-to-the-Galaxy/wiki-plugin-similarity GitHub repository]\n- [https://www.npmjs.com/package/wiki-plugin-similarity npm package]\n- [https://plugin.fedwiki.club/similarity-plugin.html Plugin documentation]\n- [https://search.fedwiki.club/ Search hub] \u2014 architecture, indexing, freshness."
+      },
+      "date": 1784706029671
     }
   ]
 }

package/server/embed-child.js

@@ -0,0 +1,120 @@
+// wiki-plugin-similarity — embedding child process (CommonJS)
+//
+// ALL onnx/transformers work happens here, in a process fork()ed by
+// embedder.js — never in the wiki-server process. A fatal error in the WASM
+// runtime (abort, OOM, bad model file) kills this child only; the parent
+// sees an exit event, fails the in-flight requests cleanly, and the farm
+// keeps serving pages. That isolation is the plugin's safety contract:
+// worst case is "semantic search unavailable", never a dead wiki.
+//
+// IPC protocol (parent → child, child → parent):
+//   {id, op: 'embed', text}  →  {id, ok: true, vector: number[384]}
+//   {id, op: 'warm'}         →  {id, ok: true}
+//   any failure              →  {id, ok: false, error}
+//
+// The child exits 0 after WIKI_EMBED_IDLE_MS without work (default 5 min)
+// so the ~0.5GB model doesn't stay pinned between searches; the parent
+// respawns on demand and doesn't count a clean exit as a crash.
+//
+// WIKI_EMBED_MOCK=1 skips the model entirely and returns deterministic
+// vectors — for tests and CI, where a text of '__CRASH__' also simulates a
+// hard crash so the parent's isolation and breaker can be exercised.
+
+const MODEL     = process.env.WIKI_EMBED_MODEL || 'Xenova/bge-small-en-v1.5'
+const POOLING   = process.env.WIKI_EMBED_POOLING || 'cls'
+const QUANTIZED = process.env.WIKI_EMBED_QUANTIZED === '1'
+const IDLE_MS   = parseInt(process.env.WIKI_EMBED_IDLE_MS) || 5 * 60_000
+const MOCK      = process.env.WIKI_EMBED_MOCK === '1'
+
+// transformers.js statically imports onnxruntime-node, whose native binary
+// needs glibc. On musl containers (node:alpine — the public farm) that import
+// throws "Error loading shared library ld-linux-x86-64.so.2". Probe the
+// native runtime with a CJS require first; if it can't load, register a
+// module hook (Node >= 18.19) that redirects the onnxruntime-node import to
+// onnxruntime-web — the WASM backend runs everywhere and benchmarks ~25ms a
+// query. WIKI_EMBED_FORCE_WASM=1 forces the WASM path for testing.
+
+const nativeOrtLoads = () => {
+  if (process.env.WIKI_EMBED_FORCE_WASM === '1') return false
+  try { require('onnxruntime-node'); return true } catch { return false }
+}
+
+let extractorPromise = null
+
+const getExtractor = () => {
+  if (!extractorPromise) {
+    extractorPromise = (async () => {
+      if (!nativeOrtLoads()) {
+        const { register } = require('node:module')
+        if (typeof register !== 'function') {
+          throw new Error('native onnxruntime unavailable and Node lacks ' +
+            'module.register (need >= 18.19) for the WASM fallback')
+        }
+        register('./ort-hooks.mjs', require('node:url').pathToFileURL(__filename))
+        console.log('[wiki-plugin-similarity] embed child: native onnxruntime unavailable — using WASM backend')
+      }
+      // Dynamic import: @xenova/transformers is ESM-only; this file must stay CJS.
+      // The heavy deps are optionalDependencies — absent on slim installs,
+      // where semindex delegation or WIKI_EMBED_URL is the path.
+      const { pipeline, env } = await import('@xenova/transformers').catch(() => {
+        throw new Error('no local embedder: @xenova/transformers is not installed. ' +
+          'Install wiki-plugin-semindex, set WIKI_EMBED_URL, or reinstall ' +
+          'wiki-plugin-similarity with optional dependencies.')
+      })
+      if (process.env.WIKI_MODEL_CACHE) env.cacheDir = process.env.WIKI_MODEL_CACHE
+      if (env.backends?.onnx?.wasm) env.backends.onnx.wasm.numThreads = 1
+      return pipeline('feature-extraction', MODEL, { quantized: QUANTIZED })
+    })()
+    extractorPromise.catch(() => { extractorPromise = null }) // allow retry
+  }
+  return extractorPromise
+}
+
+// Deterministic unit vector from text — mock mode only.
+const mockVector = text => {
+  const crypto = require('node:crypto')
+  const v = []
+  let seed = crypto.createHash('sha256').update(text).digest()
+  while (v.length < 384) {
+    for (const byte of seed) v.push((byte - 127.5) / 127.5)
+    seed = crypto.createHash('sha256').update(seed).digest()
+  }
+  const vec = v.slice(0, 384)
+  const norm = Math.sqrt(vec.reduce((s, x) => s + x * x, 0))
+  return vec.map(x => x / norm)
+}
+
+const embed = async text => {
+  if (MOCK) {
+    if (text === '__CRASH__') process.exit(13) // simulated hard crash (tests)
+    return mockVector(text)
+  }
+  const extractor = await getExtractor()
+  const out = await extractor(text, { pooling: POOLING, normalize: true })
+  return Array.from(out.data)
+}
+
+let idleTimer = null
+const bumpIdle = () => {
+  clearTimeout(idleTimer)
+  idleTimer = setTimeout(() => process.exit(0), IDLE_MS)
+}
+
+process.on('message', async msg => {
+  bumpIdle()
+  try {
+    if (msg.op === 'warm') {
+      if (!MOCK) await getExtractor()
+      process.send({ id: msg.id, ok: true })
+    } else {
+      process.send({ id: msg.id, ok: true, vector: await embed(msg.text) })
+    }
+  } catch (e) {
+    try { process.send({ id: msg.id, ok: false, error: e.message }) } catch { /* parent gone */ }
+  }
+})
+
+// Parent died or closed the channel — no reason to linger.
+process.on('disconnect', () => process.exit(0))
+
+bumpIdle()

package/server/embedder.js

@@ -1,32 +1,42 @@
-// wiki-plugin-similarity — in-process query embedder (CommonJS)
+// wiki-plugin-similarity — query embedder, child-process supervisor (CommonJS)
 //
-// Reproduces the farm indexer's embeddings (fastembed, BAAI/bge-small-en-v1.5,
-// 384-dim, L2-normalised, NO query prefix) using transformers.js — pure
-// JS/WASM ONNX, no native dependencies, so it runs inside any wiki-server
-// install including the public farm's container.
+// Since 0.9.0 the wiki-server process NEVER touches onnx/transformers: all
+// inference runs in a fork()ed embed-child.js whose crash is an event here,
+// not a farm outage. (0.8.x ran the WASM runtime in-process; a fatal error
+// there took down every site the farm served — see the 2026-07-22
+// hitchhikers.earth incident.) This module supervises the child:
 //
-// Parity notes (verified against the FastAPI /embed reference):
-//   - pooling and quantisation are configurable via env because they are the
-//     two knobs that can desync scores from the prebuilt semantic-vectors.json:
-//       WIKI_EMBED_POOLING   cls | mean   (default cls — BGE models use CLS)
-//       WIKI_EMBED_QUANTIZED 1 | 0        (default 0 — fp32 matches fastembed)
-//   - never add an instruction prefix: the index was built with plain .embed().
+//   - lazy fork on first use, V8 heap capped via --max-old-space-size
+//     (WIKI_EMBED_CHILD_HEAP_MB, default 512)
+//   - per-request timeout (WIKI_EMBED_TIMEOUT_MS, default 60s — first call
+//     includes model load; the one-time ~130MB download can exceed this,
+//     in which case warm() retries make it eventually succeed)
+//   - circuit breaker: WIKI_EMBED_MAX_CRASHES abnormal exits (default 3)
+//     within WIKI_EMBED_CRASH_WINDOW_MS (default 10 min) opens the breaker
+//     for WIKI_EMBED_COOLDOWN_MS (default 5 min); while open, embed()
+//     rejects immediately with err.code = 'EMBEDDER_DOWN' so routes can
+//     answer 503 instead of respawning a crash-loop
+//   - the child's clean idle self-exit (code 0) is not a crash
 //
-// Model files download on first use (~130MB fp32) into WIKI_MODEL_CACHE if set,
-// else transformers.js's default cache. Subsequent runs are offline.
+// Embedding parity knobs (WIKI_EMBED_MODEL / _POOLING / _QUANTIZED) are read
+// by the child from the inherited env — see embed-child.js for why they
+// exist and their defaults (bge-small-en-v1.5, cls, fp32 — must match the
+// prebuilt semantic-vectors.json).
+//
+// wiki-plugin-semindex's shared worker-thread embedder is still preferred
+// when installed: one model instance per process, shared with bulk indexing.
+// The sibling path works for npm installs (wiki/node_modules/*) and dev
+// symlinks (~/Code/wiki-plugins/*) alike; the bare require covers other
+// layouts.
 
-const MODEL     = process.env.WIKI_EMBED_MODEL || 'Xenova/bge-small-en-v1.5'
-const POOLING   = process.env.WIKI_EMBED_POOLING || 'cls'
-const QUANTIZED = process.env.WIKI_EMBED_QUANTIZED === '1'
+const path = require('node:path')
+const fs   = require('node:fs')
+const { fork } = require('node:child_process')
 
-// Prefer wiki-plugin-semindex's shared worker-thread embedder when installed:
-// one model instance per process (shared with bulk indexing), inference off
-// the event loop, and similarity's own heavy deps become optional. The
-// sibling path works for npm installs (wiki/node_modules/*) and dev symlinks
-// (~/Code/wiki-plugins/*) alike; the bare require covers other layouts.
+// WIKI_EMBED_NO_SEMINDEX=1 forces the child-process path even when semindex
+// is installed — for tests, and for opting a farm out of delegation.
 const semindexLib = (() => {
-  const path = require('node:path')
-  const fs   = require('node:fs')
+  if (process.env.WIKI_EMBED_NO_SEMINDEX === '1') return null
   try {
     const sibling = path.resolve(__dirname, '../../wiki-plugin-semindex/server/embed-lib.js')
     if (fs.existsSync(sibling)) return require(sibling)
@@ -34,61 +44,117 @@ const semindexLib = (() => {
   } catch { return null }
 })()
 
-// transformers.js statically imports onnxruntime-node, whose native binary
-// needs glibc. On musl containers (node:alpine — the public farm) that import
-// throws "Error loading shared library ld-linux-x86-64.so.2". Probe the
-// native runtime with a CJS require first; if it can't load, register a
-// module hook (Node >= 18.19) that redirects the onnxruntime-node import to
-// onnxruntime-web — the WASM backend runs everywhere and benchmarks ~25ms a
-// query. WIKI_EMBED_FORCE_WASM=1 forces the WASM path for testing.
+const HEAP_MB         = parseInt(process.env.WIKI_EMBED_CHILD_HEAP_MB) || 512
+const TIMEOUT_MS      = parseInt(process.env.WIKI_EMBED_TIMEOUT_MS) || 60_000
+const MAX_CRASHES     = parseInt(process.env.WIKI_EMBED_MAX_CRASHES) || 3
+const CRASH_WINDOW_MS = parseInt(process.env.WIKI_EMBED_CRASH_WINDOW_MS) || 10 * 60_000
+const COOLDOWN_MS     = parseInt(process.env.WIKI_EMBED_COOLDOWN_MS) || 5 * 60_000
 
-const nativeOrtLoads = () => {
-  if (process.env.WIKI_EMBED_FORCE_WASM === '1') return false
-  try { require('onnxruntime-node'); return true } catch { return false }
+const embedderError = (message, code) => {
+  const e = new Error(message)
+  if (code) e.code = code
+  return e
 }
 
-let extractorPromise = null
+let child = null
+let nextId = 1
+const inflight = new Map() // id → {resolve, reject, timer}
+
+let crashTimes = []
+let breakerOpenUntil = 0
+let lastError = null
+
+const breakerOpen = () => Date.now() < breakerOpenUntil
+
+const ensureChild = () => {
+  if (child) return child
+  child = fork(path.join(__dirname, 'embed-child.js'), [], {
+    execArgv: [`--max-old-space-size=${HEAP_MB}`],
+  })
+  child.on('message', msg => {
+    const pending = inflight.get(msg.id)
+    if (!pending) return
+    inflight.delete(msg.id)
+    clearTimeout(pending.timer)
+    if (msg.ok) pending.resolve(msg)
+    else pending.reject(embedderError(msg.error))
+  })
+  child.on('error', e => { lastError = `fork failed: ${e.message}` })
+  child.on('exit', (code, signal) => {
+    child = null
+    const abnormal = code !== 0
+    const why = signal ? `signal ${signal}` : `code ${code}`
+    for (const pending of inflight.values()) {
+      clearTimeout(pending.timer)
+      pending.reject(embedderError(`embedder process exited (${why})`))
+    }
+    inflight.clear()
+    if (!abnormal) return
+    lastError = `embed child exited: ${why}`
+    console.error(`[wiki-plugin-similarity] ${lastError}`)
+    const now = Date.now()
+    crashTimes = crashTimes.filter(t => now - t < CRASH_WINDOW_MS)
+    crashTimes.push(now)
+    if (crashTimes.length >= MAX_CRASHES) {
+      breakerOpenUntil = now + COOLDOWN_MS
+      console.error(`[wiki-plugin-similarity] ${crashTimes.length} embedder crashes in ` +
+        `${Math.round(CRASH_WINDOW_MS / 60_000)} min — semantic search disabled for ` +
+        `${Math.round(COOLDOWN_MS / 60_000)} min`)
+    }
+  })
+  return child
+}
 
-const getExtractor = () => {
-  if (!extractorPromise) {
-    extractorPromise = (async () => {
-      if (!nativeOrtLoads()) {
-        const { register } = require('node:module')
-        if (typeof register !== 'function') {
-          throw new Error('native onnxruntime unavailable and Node lacks ' +
-            'module.register (need >= 18.19) for the WASM fallback')
-        }
-        register('./ort-hooks.mjs', require('node:url').pathToFileURL(__filename))
-        console.log('[wiki-plugin-similarity] native onnxruntime unavailable — using WASM backend')
-      }
-      // Dynamic import: @xenova/transformers is ESM-only; this file must stay CJS.
-      // Since 0.8.0 the heavy deps are optionalDependencies — absent on slim
-      // installs, where semindex delegation or WIKI_EMBED_URL is the path.
-      const { pipeline, env } = await import('@xenova/transformers').catch(() => {
-        throw new Error('no local embedder: @xenova/transformers is not installed. ' +
-          'Install wiki-plugin-semindex, set WIKI_EMBED_URL, or reinstall ' +
-          'wiki-plugin-similarity with optional dependencies.')
-      })
-      if (process.env.WIKI_MODEL_CACHE) env.cacheDir = process.env.WIKI_MODEL_CACHE
-      if (env.backends?.onnx?.wasm) env.backends.onnx.wasm.numThreads = 1
-      return pipeline('feature-extraction', MODEL, { quantized: QUANTIZED })
-    })()
-    extractorPromise.catch(() => { extractorPromise = null }) // allow retry
+const request = (op, text) => {
+  if (breakerOpen()) {
+    return Promise.reject(embedderError(
+      'semantic search temporarily unavailable (embedder crashed repeatedly, cooling down)',
+      'EMBEDDER_DOWN'))
   }
-  return extractorPromise
+  return new Promise((resolve, reject) => {
+    const id = nextId++
+    const timer = setTimeout(() => {
+      inflight.delete(id)
+      reject(embedderError(`embed timed out after ${TIMEOUT_MS}ms`))
+    }, TIMEOUT_MS)
+    inflight.set(id, { resolve, reject, timer })
+    try {
+      ensureChild().send({ id, op, text })
+    } catch (e) {
+      inflight.delete(id)
+      clearTimeout(timer)
+      reject(embedderError(`embedder unavailable: ${e.message}`))
+    }
+  })
 }
 
 // Embed one text → plain number[384], unit-normalised.
 const embed = async text => {
   if (semindexLib) return semindexLib.embed(text)
-  const extractor = await getExtractor()
-  const out = await extractor(text, { pooling: POOLING, normalize: true })
-  return Array.from(out.data)
+  const { vector } = await request('embed', text)
+  return vector
 }
 
-// Warm the model in the background (call at startup; failures just defer to
-// first request). With semindex delegation, don't warm — its worker spawns on
-// demand and self-terminates when idle; pre-warming would just pin ~0.5GB.
-const warm = () => { if (!semindexLib) getExtractor().catch(() => {}) }
+// Warm the model in the background (call at startup; failures just log —
+// they can no longer crash the server). With semindex delegation, don't
+// warm — its worker spawns on demand and self-terminates when idle;
+// pre-warming would just pin ~0.5GB.
+const warm = () => {
+  if (semindexLib) return
+  request('warm').catch(e =>
+    console.error('[wiki-plugin-similarity] embedder warm failed:', e.message))
+}
+
+// Supervisor state for /system/similarity-health.json.
+const status = () => {
+  if (semindexLib) return { via: 'semindex' }
+  return {
+    via: 'child-process',
+    state: breakerOpen() ? 'down' : child ? 'running' : 'idle',
+    recentCrashes: crashTimes.filter(t => Date.now() - t < CRASH_WINDOW_MS).length,
+    breakerOpenUntil: breakerOpen() ? new Date(breakerOpenUntil).toISOString() : null,
+    lastError,
+  }
+}
 
-module.exports = { embed, warm, viaSemindex: !!semindexLib }
+module.exports = { embed, warm, status, viaSemindex: !!semindexLib }

package/server/server.js

@@ -11,9 +11,12 @@
 //   GET  /system/semantic-vectors.json[?domain=]
 //     Serves {farm}/{domain}/status/semantic-vectors.json.
 //   GET  /system/embed.json?text=…
-//     384-dim unit vector via the in-process transformers.js embedder
+//     384-dim unit vector via the crash-isolated child-process embedder
 //     (BAAI/bge-small-en-v1.5 — same model the indexes were built with).
 //     Set WIKI_EMBED_URL to proxy to an external embedder instead.
+//   GET  /system/similarity-health.json
+//     Embedder supervisor state (child-process | semindex | url, breaker,
+//     recent crashes) — 200 always; diagnosable from outside.
 //   POST /system/search-report.json  {query, domains, limit, threshold, live}
 //     Ranked, stub-filtered, fork-bundled semantic report (page JSON).
 //   GET  /system/farm-search.json?q=…&pattern=…&limit=…
@@ -216,7 +219,7 @@ const startServer = ({ argv, app }) => {
                        '/system/embed.json', '/system/search-report.json',
                        '/system/farm-search.json', '/system/build-index.json',
                        '/system/galaxy-search.json', '/system/peer-search.json',
-                       '/system/peer-hello.json']) {
+                       '/system/peer-hello.json', '/system/similarity-health.json']) {
     app.options(route, (req, res) => { cors(res); res.sendStatus(204) })
   }
 
@@ -338,10 +341,22 @@ const startServer = ({ argv, app }) => {
       res.json({ vector: await embedText(text) })
     } catch (e) {
       console.error('[wiki-plugin-similarity] embed error:', e.message)
-      res.status(502).json({ error: `embedding unavailable: ${e.message}` })
+      res.status(e.code === 'EMBEDDER_DOWN' ? 503 : 502)
+        .json({ error: `embedding unavailable: ${e.message}` })
     }
   })
 
+  // ── GET /system/similarity-health.json — embedder supervisor state ────────
+  app.get('/system/similarity-health.json', (req, res) => {
+    cors(res)
+    res.json({
+      plugin: 'wiki-plugin-similarity',
+      version: PLUGIN_VERSION,
+      ...MODEL_META,
+      embedder: EMBED_URL ? { via: 'url', url: EMBED_URL } : embedder.status(),
+    })
+  })
+
   // ── POST /system/search-report.json ────────────────────────────────────────
   // body.farms: peer farms asked to continue the search (FARM prototype).
   app.post('/system/search-report.json', async (req, res) => {
@@ -363,7 +378,8 @@ const startServer = ({ argv, app }) => {
       res.json(page)
     } catch (e) {
       console.error('[wiki-plugin-similarity] search-report error:', e.message)
-      res.status(500).json({ error: `search-report failed: ${e.message}` })
+      res.status(e.code === 'EMBEDDER_DOWN' ? 503 : 500)
+        .json({ error: `search-report failed: ${e.message}` })
     }
   })
 
@@ -496,7 +512,8 @@ const startServer = ({ argv, app }) => {
         farm: req.hostname, sites: grantedNames.length, count } })
     } catch (e) {
       console.error('[wiki-plugin-similarity] peer-search error:', e.message)
-      res.status(500).json({ error: `peer-search failed: ${e.message}` })
+      res.status(e.code === 'EMBEDDER_DOWN' ? 503 : 500)
+        .json({ error: `peer-search failed: ${e.message}` })
     }
   })