@fangorn-network/westmarch 0.0.1-dev → 0.0.2-dev

package/README.md

@@ -1,4 +1,4 @@
-# @fangorn/westmarch
+# @fangorn-network/westmarch
 
 Everything you need to get started building apps with Fangorn.
 
@@ -235,7 +235,7 @@ like: a short file that holds the constants still and re-exports the rest.
 ## What an app has to wire
 
 ```js
-import { configure } from "@fangorn/westmarch/shard";
+import { configure } from "@fangorn-network/westmarch/shard";
 
 configure({
   // How to learn WHICH view to read. A callback, not a constant: a view id

package/consume/apps.js

@@ -37,8 +37,10 @@ export const APP_EXTENSION = "https://fangorn.network/a2a/app/v1";
 export function toApp({ card, appId, fromBlock, namespaces }, cardUrl) {
     const ext = card.capabilities.extensions.find((e) => e.uri === APP_EXTENSION);
     const views = (Array.isArray(ext?.params?.views) ? ext.params.views : []).map(safeView).filter(Boolean);
+    const p = ext?.params?.paid;
+    const paid = p && /^https?:\/\//.test(p.url ?? "") && p.url.includes("{id}") && /^\d+$/.test(String(p.price)) ? p : null;
     return {
-        appId, card: cardUrl, fromBlock, namespaces, views,
+        appId, card: cardUrl, fromBlock, namespaces, views, paid,
         name: card.name ?? appId,
         desc: card.description ?? "",
         url: safeView(card.url),
@@ -69,7 +71,7 @@ export async function listApps(fangorn, { fromBlock, toBlock } = {}) {
 }
 
 // ── self-check: `node consume/apps.js` ──────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/apps.js")) {
     const j = (x) => JSON.stringify(x, (_, v) => (typeof v === "bigint" ? `${v}n` : v));
     const eq = (a, b, m) => { if (j(a) !== j(b)) throw new Error(`${m}: ${j(a)} != ${j(b)}`); };
     const A = "0x" + "a".repeat(64), B = "0x" + "b".repeat(64), C = "0x" + "c".repeat(64);

package/consume/corpora.js

@@ -189,7 +189,7 @@ export function follow(picks = [], corpora = [], { at = null } = {}) {
 }
 
 // ── self-check: `node consume/corpora.js` ───────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/corpora.js")) {
     const s = session();
     const add = (view, name, n) => {
         const c = s.slot(view);

package/consume/directory.js

@@ -168,7 +168,7 @@ export async function sourcesFromChain(fangorn, opts) {
 }
 
 // ── self-check: `node consume/directory.js` ─────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/directory.js")) {
     const warn = console.warn; console.warn = () => {};
     const cov = (...vectors) => ({ dim: 2, sampled: 100, vectors, counts: vectors.map(() => 50) });
 

package/consume/embed.js

@@ -214,7 +214,7 @@ export const warmEmbedder = () => {
 };
 
 // ── self-check: `node src/llm/embed.js` — quantization only, no model download ────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/embed.js")) {
     const v = matryoshka(Array.from({ length: 768 }, (_, i) => Math.sin(i)));
     let norm = 0;
     for (const x of v) norm += x * x;

package/consume/lint.js

@@ -306,7 +306,7 @@ export function format(r) {
 }
 
 // ── cli + self-check: `node consume/lint.js [viewUrl]` ─────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/lint.js")) {
     const arg = process.argv.slice(2).find((a) => !a.startsWith("--"));
     if (arg) {
         console.log(format(await lint(arg, { rows: !process.argv.includes("--no-rows") })));

package/consume/mcp-bin.js

@@ -0,0 +1,6 @@
+// Entry for the single-file `fangorn-mcp` (build-bin.js), not for node.
+// Static imports run in order, so the library is loaded before the server
+// starts. Not `await import("./mcp.js")`: bun 1.1 then wraps each module in a
+// function, and their top-level awaits stop parsing.
+import "./ort-preload.js";
+import "./mcp.js";

package/consume/mcp.js

@@ -24,15 +24,20 @@
 // dies is reopened on the next call.
 
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { mkdirSync, readFileSync, existsSync, rmSync, writeFileSync, renameSync } from "node:fs";
+import { createHash } from "node:crypto";
+import net from "node:net";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
-import { APP_EXTENSION, listApps } from "./apps.js";
+import { APP_EXTENSION, listApps, toApp } from "./apps.js";
 
 // The current AppRegistry's first event on Arbitrum Sepolia. A reader's
 // default, not deployment config: pass --from-block for another deployment.
 const DEFAULT_FROM_BLOCK = 311637349n;
 const log = (...a) => console.error("[fangorn-mcp]", ...a);   // stdout is the protocol
+// FANGORN_MCP_TRACE=1: step timings on stderr, for finding where an answer waits.
+const T0 = performance.now();
+const trace = process.env.FANGORN_MCP_TRACE ? (what) => log(`${Math.round(performance.now() - T0)}ms ${what}`) : () => {};
 
 let client;
 async function fangorn() {
@@ -40,6 +45,15 @@ async function fangorn() {
         const [{ Fangorn, FangornConfig }, { generatePrivateKey }] = await Promise.all([
             import("@fangorn-network/sdk"), import("viem/accounts")]);
         client = Fangorn.create({ privateKey: generatePrivateKey(), config: FangornConfig });   // reads only
+        // list-apps verifies every card and open-app verifies one again: once a minute is enough.
+        const verify = client.discoverApp.bind(client), seen = new Map();
+        client.discoverApp = (url) => {
+            const hit = seen.get(url);
+            if (hit && Date.now() - hit.at < 60_000) return hit.p;
+            const p = verify(url).catch((e) => { seen.delete(url); throw e; });
+            seen.set(url, { at: Date.now(), p });
+            return p;
+        };
     }
     return client;
 }
@@ -49,10 +63,69 @@ async function fangorn() {
 async function resolveCard(cardUrl) {
     const card = await (await fetch(cardUrl)).json();
     const fangornApp = card.capabilities?.extensions?.some((e) => e.uri === APP_EXTENSION);
-    if (fangornApp) await (await fangorn()).discoverApp(cardUrl);
+    // Views only from a verified card, and only http(s) ones (toApp filters).
+    const app = fangornApp ? toApp(await (await fangorn()).discoverApp(cardUrl), cardUrl) : null;
     const page = new URL(card.url);
     if (page.protocol !== "https:" && page.protocol !== "http:") throw new Error(`card.url is not http(s): ${card.url}`);
-    return { card, page: page.toString(), verified: fangornApp };
+    return { card, page: page.toString(), verified: fangornApp, views: app?.views ?? [], paid: app?.paid ?? null };
+}
+
+// ── the network ─────────────────────────────────────────────────────────────
+// Every byte an answer waits on, cached where it is safe to:
+//   - a content-addressed file (`…-<12 hex>.<ext>`, every shard) never changes,
+//     so it is kept on disk forever. shard.js still checks it against the
+//     manifest's sha256, so a bad cache entry fails loudly, not silently.
+//   - catalogs, manifests and cards change on a rebake: held for a minute, so
+//     one search (or resolving then verifying a card) does not fetch each twice.
+const CACHE = `${homedir()}/.cache/fangorn-mcp`;
+/** Stale-while-revalidate from disk: the last copy at once, a fresh one fetched
+ *  behind it for next time. Only for reads where stale is harmless. */
+function staleFetch(fetcher) {
+    mkdirSync(`${CACHE}/stale`, { recursive: true });
+    return async (url) => {
+        const f = `${CACHE}/stale/${createHash("sha256").update(url).digest("hex")}`;
+        const refresh = fetcher(url).then(async (r) => {
+            if (!r.ok) return r;
+            const b = new Uint8Array(await r.arrayBuffer());
+            writeFileSync(`${f}.tmp`, b); renameSync(`${f}.tmp`, f);
+            return new Response(b);
+        });
+        if (existsSync(f)) { refresh.catch(() => {}); return new Response(readFileSync(f)); }
+        return refresh;
+    };
+}
+
+function cachingFetch(real = globalThis.fetch) {
+    mkdirSync(`${CACHE}/blobs`, { recursive: true });
+    const memo = new Map();
+    return async (input, init) => {
+        const url = String(input?.url ?? input);
+        if ((init?.method ?? input?.method ?? "GET") !== "GET" || !/^https?:/.test(url)) return real(input, init);
+        const path = new URL(url).pathname;
+        if (/-[0-9a-f]{12}\.[a-z.]+$/.test(path)) {
+            const f = `${CACHE}/blobs/${createHash("sha256").update(url).digest("hex")}`;
+            if (existsSync(f)) return new Response(readFileSync(f));
+            const r = await real(input, init);
+            if (!r.ok) return r;
+            const b = new Uint8Array(await r.arrayBuffer());
+            writeFileSync(`${f}.tmp`, b); renameSync(`${f}.tmp`, f);   // never a torn file
+            return new Response(b, { headers: r.headers });
+        }
+        // A card, catalog or manifest is small: 8s without one means the host is
+        // down, and a dead card in the directory must not stall a listing for a
+        // TCP timeout. Shards get no deadline; a big file on a slow link is legitimate.
+        init = { ...init, signal: init?.signal ?? AbortSignal.timeout(8000) };
+        if (/\/cdn\/catalog$|\/manifest$|\/agent-card\.json$/.test(path)) {
+            const hit = memo.get(url);
+            if (hit && Date.now() - hit.at < 60_000) return new Response(hit.body, { headers: hit.headers });
+            const r = await real(input, init);
+            if (!r.ok) return r;
+            const body = new Uint8Array(await r.arrayBuffer());
+            memo.set(url, { at: Date.now(), body, headers: r.headers });
+            return new Response(body, { headers: r.headers });
+        }
+        return real(input, init);
+    };
 }
 
 // ── the browser ─────────────────────────────────────────────────────────────
@@ -93,7 +166,8 @@ async function localChrome({ headed }) {
     ], { stdio: "ignore" });
     const failed = new Promise((_, j) => proc.on("error", (e) => j(new Error(
         `no browser: cannot launch ${bin} (${e.code}). Point --cdp / FANGORN_MCP_CDP at a WebMCP browser, or set CHROME.`))));
-    for (let i = 0; i < 100; i++) {
+    // 30s: a cold start on a loaded machine or CI box has taken 16s.
+    for (let i = 0; i < 300; i++) {
         await Promise.race([new Promise((r) => setTimeout(r, 100)), failed]);
         if (existsSync(portFile)) return { ws: await browserWs(`http://127.0.0.1:${readFileSync(portFile, "utf-8").split("\n")[0]}`), proc };
     }
@@ -211,8 +285,8 @@ const META = [
       description: "List the Fangorn apps registered on chain whose agent cards verify: name, description, card URL, and the WebMCP tools each page offers. Filter with `query`. Call open-app on one to use its tools.",
       inputSchema: { type: "object", properties: { query: { type: "string", description: "Case-insensitive match on name or description" } } } },
     { name: "open-app",
-      description: "Verify an app's card against the chain, open its page in a browser tab, and add its tools to this server as `<app>__<tool>`. Returns the tools and their input schemas. `app` is a name from list-apps, an appId, or a card URL.",
-      inputSchema: { type: "object", properties: { app: { type: "string" } }, required: ["app"] } },
+      description: "Verify an app's card against the chain and add its tools to this server as `<app>__<tool>`. An app that publishes views gets fast data tools (describe, search, get, similar, count, browse) with no browser. `page: true` also opens the app's page in a browser for its own WebMCP tools (slower). `app` is a name from list-apps, an appId, or a card URL.",
+      inputSchema: { type: "object", properties: { app: { type: "string" }, page: { type: "boolean", description: "Also load the page's own WebMCP tools in a browser" } }, required: ["app"] } },
     { name: "call-app-tool",
       description: "Call one tool of an opened app. Same as calling `<app>__<tool>` directly.",
       inputSchema: { type: "object", properties: { app: { type: "string" }, tool: { type: "string" }, arguments: { type: "object" } }, required: ["app", "tool"] } },
@@ -221,46 +295,73 @@ const META = [
 /**
  * The server. `deps` is the outside world, so the self-check can fake it:
  *   findApps()          → { apps: [{ name, desc, card, appId }], rejected }
- *   resolveCard(url)    → { card, page, verified }
+ *   findByName(name)    → { card, appId } | null     (optional: a direct registry read)
+ *   resolveCard(url)    → { card, page, verified, views }
+ *   viewTools(app)      → { tools, call(name, args) } | null   (no browser)
  *   openTab(page)       → ev
  *   tabTools(ev), tabCall(ev, name, args)
  *   notify(method)      set after serve()
  */
 export function handlers(deps) {
-    const open = new Map();   // slug → { name, card, verified, ev, tools }
+    const open = new Map();   // slug → { name, card, verified, page, views?, pages?, tools }
 
     const findOpen = (app) => open.get(slug(app)) ?? [...open.values()].find((o) => o.card === app || o.appId === app);
+    const retool = (o) => {
+        const taken = new Set(o.views?.tools.map((t) => t.name));
+        // A page tool that shares a data tool's name is kept, under `page-<name>`.
+        o.pageNames = new Map((o.pageTools ?? []).map((t) => [taken.has(t.name) ? `page-${t.name}` : t.name, t.name]));
+        o.tools = [...(o.views?.tools ?? []), ...(o.pageTools ?? []).map((t) => ({ ...t, name: taken.has(t.name) ? `page-${t.name}` : t.name }))];
+    };
+    async function openPage(o) {
+        o.ev = await deps.openTab(o.page);
+        o.pageTools = await deps.tabTools(o.ev);
+    }
 
-    async function openApp(app) {
+    async function openApp(app, { page = false } = {}) {
         const hit = findOpen(app);
-        if (hit) return hit;
-        let cardUrl = app, appId;
-        if (!/^https?:\/\//.test(app)) {
-            const { apps } = await deps.findApps();
-            const a = apps.find((x) => x.appId === app || slug(x.name) === slug(app));
-            if (!a) throw new Error(`no verified app named ${JSON.stringify(app)}; see list-apps`);
-            ({ card: cardUrl, appId } = a);
+        if (hit && (hit.ev || !page)) return hit;
+        let o = hit;
+        if (!o) {
+            let cardUrl = app, appId;
+            if (!/^https?:\/\//.test(app)) {
+                // One registry read when the name is the app's own; the scan only when it is not.
+                trace(`open ${app}: lookup`);
+                const a = await deps.findByName?.(app)
+                    ?? (await deps.findApps()).apps.find((x) => x.appId === app || slug(x.name) === slug(app));
+                if (!a) throw new Error(`no verified app named ${JSON.stringify(app)}; see list-apps`);
+                ({ card: cardUrl, appId } = a);
+            }
+            trace(`open ${app}: resolve ${cardUrl}`);
+            const { card, page: url, verified, views, paid } = await deps.resolveCard(cardUrl);
+            trace(`open ${app}: verified`);
+            let s = slug(card.name ?? app);
+            while (open.has(s)) s += "-";
+            o = { slug: s, name: card.name, card: cardUrl, appId, verified, page: url,
+                  views: deps.viewTools?.({ name: card.name, desc: card.description, views, paid }) ?? null };
         }
-        const { card, page, verified } = await deps.resolveCard(cardUrl);
-        let s = slug(card.name ?? app);
-        while (open.has(s)) s += "-";
-        const ev = await deps.openTab(page);
-        const entry = { slug: s, name: card.name, card: cardUrl, appId, verified, page, ev, tools: await deps.tabTools(ev) };
-        open.set(s, entry);
+        // The browser only when asked, or when there is no other way in.
+        if (page || !o.views) await openPage(o);
+        retool(o);
+        trace(`open ${app}: ready`);
+        open.set(o.slug, o);
         deps.notify?.("notifications/tools/list_changed");
-        return entry;
+        return o;
     }
 
     async function call(app, tool, args) {
         const o = findOpen(app);
         if (!o) throw new Error(`${app} is not open; call open-app first`);
-        try { return await deps.tabCall(o.ev, tool, args); }
+        if (!o.pageNames?.has(tool)) {
+            if (o.views?.tools.some((t) => t.name === tool)) return o.views.call(tool, args);
+            throw new Error(`${o.slug} has no tool ${tool}${o.ev ? "" : " (its page tools load with open-app page: true)"}`);
+        }
+        const name = o.pageNames.get(tool);
+        try { return await deps.tabCall(o.ev, name, args); }
         catch (e) {
             if (!/tab closed/.test(e.message)) throw e;
             // The tab or the whole browser went away. Reopen once; the tools keep their names.
-            o.ev = await deps.openTab(o.page);
-            await deps.tabTools(o.ev);
-            return deps.tabCall(o.ev, tool, args);
+            await openPage(o);
+            return deps.tabCall(o.ev, name, args);
         }
     }
 
@@ -276,9 +377,10 @@ export function handlers(deps) {
                 unverified: rejected.length,
             });
         },
-        "open-app": async ({ app }) => {
-            const o = await openApp(app);
-            return text({ app: o.slug, name: o.name, page: o.page, verified: o.verified,
+        "open-app": async ({ app, page }) => {
+            const o = await openApp(app, { page });
+            return text({ app: o.slug, name: o.name, verified: o.verified,
+                          data_tools: !!o.views, page_tools: o.ev ? o.page : false,
                           call_as: `${o.slug}__<tool>, or call-app-tool`, tools: o.tools });
         },
         "call-app-tool": async ({ app, tool, arguments: args }) => call(app, tool, args),
@@ -289,7 +391,7 @@ export function handlers(deps) {
             protocolVersion: p.protocolVersion ?? "2025-06-18",
             capabilities: { tools: { listChanged: true } },
             serverInfo: { name: "fangorn-mcp", version: "0.1.0" },
-            instructions: "Fangorn apps are static sites whose tools run in the browser. list-apps to find one, open-app to load it, then call its tools as <app>__<tool>.",
+            instructions: "Fangorn apps are static sites anchored on chain. list-apps to find one, open-app to load it, then call its tools as <app>__<tool>. Start with <app>__describe when it exists.",
         }),
         ping: async () => ({}),
         "tools/list": async () => ({ tools: [
@@ -349,11 +451,40 @@ if (process.argv[2] === "--selfcheck") {
     assert(body(8).args.who === "a" && body(9).name === "greet", "both call paths reach the tab");
     assert(res(10).result.isError && res(11).result.isError, "failures are tool errors");
     assert(res(12).error.code === -32601, "unknown method");
-    console.log("mcp.js self-check ok — one server, apps opened on demand, their tools listed as <app>__<tool>");
+
+    // An app with views: data tools, no browser, until page: true.
+    {
+        const out2 = new PassThrough(), in2 = new PassThrough(), r2 = [];
+        createInterface({ input: out2 }).on("line", (l) => r2.push(JSON.parse(l)));
+        let tabs = 0;
+        const d2 = { ...deps,
+            resolveCard: async () => ({ card: { name: "Kings Foil" }, page: "https://k.test/p", verified: true, views: ["https://k.test/v"] }),
+            viewTools: (app) => ({ tools: [{ name: "search" }, { name: "greet" }], call: async (n, a) => text({ via: "views", n, a, views: app.views }) }),
+            openTab: async () => (tabs++, "ev"),
+        };
+        d2.notify = serve(handlers(d2), { input: in2, output: out2 });
+        const q = (id, name, args) => in2.write(JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }) + "\n");
+        const got = (id) => r2.find((r) => r.id === id)?.result;
+        q(1, "open-app", { app: "Kings Foil" }); await wait(); q(2, "kings-foil__search", { query: "x" }); await wait();
+        assert(tabs === 0 && JSON.parse(got(1).content[0].text).data_tools, "views mean no browser");
+        assert(JSON.parse(got(2).content[0].text).via === "views", "data tools answer from the views");
+        q(3, "open-app", { app: "kings-foil", page: true }); await wait();
+        const names = JSON.parse(got(3).content[0].text).tools.map((t) => t.name);
+        assert(tabs === 1 && names.includes("search") && names.includes("greet") && names.includes("page-greet"), `page: true adds page tools, a clash renamed: ${names}`);
+        q(4, "kings-foil__page-greet", { who: "p" }); q(5, "kings-foil__greet", {}); await wait();
+        assert(JSON.parse(got(4).content[0].text).ev === "ev" && JSON.parse(got(5).content[0].text).via === "views", "each name reaches its own side");
+    }
+    console.log("mcp.js self-check ok — one server, apps opened on demand, data tools without a browser, page tools on request");
     process.exit(0);
 }
 
 const argv = process.argv.slice(2);
+globalThis.fetch = cachingFetch();
+// Node gives each address 250ms before trying the next; on a slow link, or a
+// host with no working IPv6, every attempt times out and fetch fails outright.
+net.setDefaultAutoSelectFamilyAttemptTimeout?.(2000);
+const vt = await import("./view-tools.js");
+const stale = staleFetch(globalThis.fetch);
 const fb = argv.indexOf("--from-block");
 const fromBlock = fb >= 0 ? BigInt(argv[fb + 1]) : DEFAULT_FROM_BLOCK;
 const headed = argv.includes("--headed");
@@ -373,9 +504,37 @@ const deps = {
         }
         return found;
     },
+    findByName: async (name) => {
+        const [f, { appId }] = await Promise.all([fangorn(), import("@fangorn-network/sdk")]);
+        const reg = f.getAppRegistry();
+        for (const id of /^0x[0-9a-fA-F]{64}$/.test(name) ? [name] : [...new Set([name, name.toLowerCase()])].map(appId)) {
+            const card = await reg.appAgentUri(id).catch(() => "");
+            if (card) return { card, appId: id };
+        }
+        return null;
+    },
     resolveCard,
+    viewTools: (app) => {
+        const v = vt.viewTools(app, { fetchCatalog: stale });
+        if (v) vt.warm({ cacheDir: `${CACHE}/models` });   // already started at initialize; this is the fallback
+        return v;
+    },
     openTab: (page) => openTab(page, { headed, cdp }),
     tabTools, tabCall,
 };
-deps.notify = serve(handlers(deps));
+const h = handlers(deps);
+// The client starts this server with the session, long before an agent opens an
+// app: load the SDK and the embedding model then, behind the agent's first
+// thought. After the initialize reply, not before: both block the thread while
+// they load, and the client is waiting on that reply.
+const reply = h.initialize;
+h.initialize = async (p) => {
+    setImmediate(() => {
+        fangorn().then(() => trace("sdk ready"), () => {});
+        vt.warm({ cacheDir: `${CACHE}/models` }).then((ok) => ok ? trace("embedder ready")
+            : log(`embedder unavailable, searching by words: ${vt.warmError}`));
+    });
+    return reply(p);
+};
+deps.notify = serve(h);
 log(`ready: apps from block ${fromBlock}; browser ${cdp ?? "local Chrome"}, connected on the first open-app`);

package/consume/ort-preload.js

@@ -0,0 +1,25 @@
+// Loads onnxruntime's library for the single-file `fangorn-mcp` (mcp-bin.js).
+//
+// bun embeds onnxruntime's binding and extracts it to a temp dir at run time,
+// but not the library the binding links against, so the embedder fails to load.
+// This embeds that library too, writes it to the cache once, and loads it before
+// anything imports transformers: the binding then finds it already loaded, by name.
+// A failure here only costs the embedder, and search falls back to words.
+import { dlopen } from "bun:ffi";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+// build-bin.js puts the target's library here before it compiles.
+import lib from "../dist/ort/libonnxruntime.so.1" with { type: "file" };
+
+try {
+    const dir = `${homedir()}/.cache/fangorn-mcp/lib/${lib.split("/").pop()}`;   // bun names it by content hash
+    const path = `${dir}/libonnxruntime.so.1`;
+    if (!existsSync(path)) {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(`${path}.${process.pid}`, readFileSync(lib));   // copyFile cannot read bun's embedded fs
+        renameSync(`${path}.${process.pid}`, path);
+    }
+    dlopen(path, { OrtGetApiBase: { args: [], returns: "ptr" } });   // bun wants one symbol; this is the lib's entry point
+} catch (e) {
+    console.error(`[fangorn-mcp] onnxruntime not loaded, search will rank by words: ${e.message}`);
+}

package/consume/rank.js

@@ -159,7 +159,7 @@ export function rankDomains(domains = [], q) {
 }
 
 // ── self-check: `node consume/rank.js` ──────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/rank.js")) {
     // Word boundaries: the bug this replaced ranked "intoxicated" for "cat".
     if (lexScore({ text: "intoxicated education" }, "cat") !== 0) throw new Error("substring matched — word boundaries lost");
     if (lexScore({ text: "a cat sat" }, "cat") <= 0) throw new Error("whole word must match");

package/consume/roles.js

@@ -66,7 +66,7 @@ export function rolesFrom(manifests = [], sample = []) {
     const seen = new Set();
     for (const r of sample) for (const k of Object.keys(r)) seen.add(k);
 
-    const title = [], subtitle = [], tags = [], text = [], measures = [], spatial = [], media = [];
+    const title = [], subtitle = [], tags = [], text = [], measures = [], spatial = [], media = [], temporal = [], facets = [];
     const labels = {}, types = {}, fieldLabels = {}, externalUrl = {}, actions = {};
     let launch = null, refers = null;
     const entityTypes = [];
@@ -78,7 +78,7 @@ export function rolesFrom(manifests = [], sample = []) {
     for (const m of manifests) {
         const rm = m?.role_map ?? {};
         push(title, rm.title); push(subtitle, rm.subtitle); push(tags, rm.tags);
-        push(text, rm.text); push(measures, rm.measures); push(spatial, rm.spatial); push(media, rm.media);
+        push(text, rm.text); push(measures, rm.measures); push(spatial, rm.spatial); push(media, rm.media); push(temporal, rm.temporal);
         identity ??= rm.identity ?? null;
         // Where a row in THIS corpus points, in someone else's.
         //
@@ -101,6 +101,8 @@ export function rolesFrom(manifests = [], sample = []) {
         Object.assign(fieldLabels, pr.fieldLabels ?? {});
         Object.assign(externalUrl, pr.externalUrl ?? {});
         Object.assign(actions, pr.actions ?? {});
+        // The fields a reader narrows by first (a town, a genre): the app's to name.
+        push(facets, pr.facets);
         // The app's own interface, if it ships one. A url, not markup: it is a
         // separate document with a separate origin, which is the only way a
         // stranger's UI can be run at all.
@@ -135,7 +137,7 @@ export function rolesFrom(manifests = [], sample = []) {
     guess(text, GUESS.text);
 
     return {
-        title, subtitle, tags, text, measures, spatial, media, identity,
+        title, subtitle, tags, text, measures, spatial, media, temporal, facets, identity,
         labels, types, fieldLabels, externalUrl, actions, launch, refers, entityTypes,
         // What this view sells, if anything. A list because a fused view can pull
         // domains from several publishers and they price independently.
@@ -365,7 +367,7 @@ export function actionsOf(row, roles) {
 }
 
 // ── self-check: `node consume/roles.js` ─────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/roles.js")) {
     // The real places manifest's shape.
     const places = {
         role_map: {

package/consume/shard.js

@@ -438,7 +438,7 @@ export async function suggestDomains(q, { url } = {}) {
 }
 
 // ── self-check: `node consume/shard.js` — no network, no view ────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/shard.js")) {
     const { gzipSync } = await import("node:zlib");
     const warn = console.warn, info = console.info;
     console.warn = console.info = () => {}; // the fallback warnings are behaviour under test, not output

package/consume/steam.js

@@ -237,7 +237,7 @@ export const summarize = (seed) =>
     `${seed.hours} hours · ${seed.likes.length} liked, ${seed.dislikes.length} bounced off`;
 
 // ── self-check: `node consume/steam.js` ─────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/steam.js")) {
     // A localconfig.vdf, cut down but structurally exact — including the mixed
     // casing of the Valve/valve segment that defeats a hardcoded path.
     const VDF = `

package/consume/taste-doc.js

@@ -236,7 +236,7 @@ export function tasteDoc({ t = null, catalogues = [], instructions = "", now = n
 }
 
 // ── self-check: `node consume/taste-doc.js` ─────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/taste-doc.js")) {
     const { taste } = await import("./taste.js");
 
     // A catalogue with a KNOWN shape: two axes, and a tag at each end of each.

package/consume/taste.js

@@ -212,7 +212,7 @@ export function withProvenance(t, { carried = null, likes = [], dislikes = [] }
 }
 
 // ── self-check: `node consume/taste.js` ─────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/taste.js")) {
 
     // recommend() returns {row, score} — NOT {row, s}. kingsfoil's agent read
     // h.s and reported every recommendation with score: undefined.

package/consume/tools.js

@@ -12,7 +12,7 @@
 // Pure functions, so `node tools.js` checks them with no browser and no network.
 
 import { bestPassage, cosine, lexScore, norm, zFloor } from "./rank.js";
-import { briefOf, collections, linkOf, titleOf, typeOf, values } from "./roles.js";
+import { briefOf, collections, linkOf, subtitleOf, titleOf, typeOf, values } from "./roles.js";
 
 /** Fields that are plumbing rather than content — never worth faceting or
  *  showing as "what this corpus holds". */
@@ -72,7 +72,27 @@ export function describe(rows) {
  * `qv` is passed in, not computed: embedding is async and model-shaped, and
  * keeping it out here is what lets this file be a pure-function self-check.
  */
-export function search(rows, query, roles, { qv = null, limit = 10, fields, where } = {}) {
+/** How much an exact word match adds to a cosine. Meaning alone ranks "wisconsin rapids"
+ *  by what the towns have in common (every row is in Wisconsin), so an Eau Claire item
+ *  about a bike ride "across Wisconsin" beat every Wisconsin Rapids one. The words decide
+ *  among rows that mean about the same thing; they never outvote meaning outright.
+ *  Measured on Quorum's eval (quorum/eval/search.mjs, 11k rows), top-5 precision / known @1:
+ *  0 → towns 92%, topics 88%, @1 91%;  0.1 → 100/94/97;  0.15 → 100/98/98.5;  0.3 → 100/98/97. */
+export const LEX_BOOST = 0.15;
+
+// The words a row can be found by: its title, subtitle and tags, not only its prose.
+// A town, a body or a kind lives in the tags, and "Plover" should find Plover's items.
+const lexCache = new WeakMap();
+const lexText = (r, roles) => {
+    let t = lexCache.get(r);
+    if (t === undefined) {
+        t = [titleOf(r, roles), subtitleOf(r, roles) ?? "", ...(roles.tags ?? []).flatMap((f) => values(r[f] ?? "")), r.text ?? ""].join(" ");
+        lexCache.set(r, t);
+    }
+    return t;
+};
+
+export function search(rows, query, roles, { qv = null, limit = 10, fields, where, lexBoost = LEX_BOOST } = {}) {
     const ql = query.trim().toLowerCase();
     if (!ql) return [];
     const qn = qv ? norm(qv) : 1;
@@ -84,8 +104,8 @@ export function search(rows, query, roles, { qv = null, limit = 10, fields, wher
     // ever answers the question the way it was asked.
     if (where) rows = rows.filter((r) => matches(r, where));
     const scored = rows.map((r) => (qv && r.vector
-        ? { r, score: cosine(r, qv, qn), mode: "semantic" }
-        : { r, score: lexScore(r, ql), mode: "lexical" }));
+        ? { r, score: cosine(r, qv, qn) + (lexBoost ? lexBoost * lexScore({ text: lexText(r, roles) }, ql) : 0), mode: "semantic" }
+        : { r, score: lexScore({ text: lexText(r, roles) }, ql), mode: "lexical" }));
     // The floor is per QUERY over the whole corpus, so it is measured before
     // anything is dropped. Raw cosine is offset per query, not per corpus: on this
     // catalog every row scores 0.38–0.65 against anything, and `score > 0` admits
@@ -200,7 +220,10 @@ export function getRow(rows, id, roles) {
     // id first, then whatever the publisher calls a title — an agent that read a
     // title off a search result and passed it back must land on the same row.
     if (!id) return null;   // else `x.path === undefined` matches the first row lacking one
+    // A view built from commits keys rows by vertex CID, so the publisher's own id
+    // (the declared identity field) has to find them too.
     const r = rows.find((x) => x.id === id)
+        ?? (roles?.identity ? rows.find((x) => String(x[roles.identity]) === String(id)) : null)
         ?? rows.find((x) => x.path === id || x.name === id || titleOf(x, roles) === id);
     if (!r) return null;
     const { vector, norm: _n, ...rest } = r;
@@ -208,7 +231,7 @@ export function getRow(rows, id, roles) {
 }
 
 // ── self-check: `node tools.js` — no browser, no network ────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/tools.js")) {
     const { rolesFrom } = await import("./roles.js");
     const row = (id, fields, vector) => ({
         id, owner: "0xa", ...fields,

package/consume/ui.js

@@ -505,7 +505,7 @@ export function stage({ picks = [], heading = "", note = "" } = {}) {
 }
 
 // ── self-check: `node consume/ui.js` ────────────────────────────────────────
-if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}`) {
+if (typeof process !== "undefined" && import.meta.url === `file://${process.argv[1]}` && process.argv[1].endsWith("/ui.js")) {
     const roles = { measures: ["rating", "year", "runtime", "votes"] };
     const html = rankedList({
         heading: 'search "frozen"', note: "2 corpora",