@barivia/barmesh-mcp 0.7.1 → 0.8.2

package/README.md

@@ -13,16 +13,16 @@ form on a shared self-organizing map (SOM)**:
 - **`barmesh_mesh_convergence`** — trains one SOM on all meshes (joint-normalized), projects
   each mesh to a volume-weighted fingerprint, and computes **symmetric KL** and
   **Wasserstein-1 (EMD)** distances stepwise and against a reference mesh, with publication
-  figures and an advisory convergence reading. The SOM features are preprocessed by the
-  same staged pipeline as barsom training, so any dataset (small or large, CSV/gzip)
-  is handled out-of-core by default; optional `transforms`, `normalize`,
-  `normalization_methods`, and `row_range` give the same preprocessing controls. Submit
-  enqueues **`prepare_training_matrix`** on worker-io when the dataset is staged; the proxy
-  auto-polls `prepare_job_id` before the mesh job runs. Default **`defer_figures=true`** →
-  **`cfd_finalize`** on worker-io; **`barmesh_jobs(status)`** auto-polls **`finalize_job_id`**
-  when figures are deferred.
+  figures and an advisory convergence reading. Default **`mesh_order`** sorts by ascending
+  cell count and **interleaves U/G (or similar) families** when counts tie, so stepwise
+  distances do not jump across topology families. The SOM features use the same staged
+  pipeline as barsom training; optional `transforms`, `normalize`, `normalization_methods`,
+  and `row_range` apply. Submit enqueues **`prepare_training_matrix`** on worker-io when
+  staged; the proxy auto-polls `prepare_job_id`. Default **`defer_figures=true`** →
+  **`cfd_finalize`**; **`barmesh_jobs(status)`** auto-polls **`finalize_job_id`**.
 - **`barmesh_richardson`** — classical three-level Richardson extrapolation / Grid
-  Convergence Index (GCI) on scalar quantities of interest.
+  Convergence Index (GCI) on scalar quantities of interest. Prefer **one topology family**
+  (all U or all G); mixed families return a **`topology_warning`** in the result summary.
 
 These complement, and do not replace, conventional numerical uncertainty analysis.
 
@@ -56,9 +56,9 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 | `barmesh_mesh_convergence` | SOM fingerprint distances (async job). |
 | `barmesh_richardson` | Richardson/GCI on scalar QoIs (async job). |
 | `barmesh_jobs` | Poll job status / block until terminal (`action=monitor`) / list jobs. Auto-polls CFD prepare + finalize when applicable. Reports phase, epoch/total, elapsed, ETA, and QE live during the SOM training. |
-| `barmesh_training_monitor` | Alias for `barmesh_jobs(action=monitor)` — server-side poll with throttled snapshots until terminal (preferred after submit). |
-| `barmesh_results` | Distances, convergence reading, and figures. `action=get` inlines headline PNGs; `action=download` saves artifacts to disk; `action=render` produces publication PDFs on demand. |
-| `barmesh_results_explorer` | Interactive MCP App with a **figure dropdown above the plot** (or standalone localhost page) to browse every figure after a job completes. |
+| `barmesh_training_monitor` | Live MCP App (QE + panel TE) and/or headless monitor; always returns a standalone localhost URL + `ui_delivery`. |
+| `barmesh_results` | Distances, convergence reading, and figures. `action=get` inlines headline PNGs; `action=download` saves artifacts to disk; `action=render` produces publication PDFs on demand; `action=feature_divergences` refreshes feature-plane KL/W1 (distinct from mesh SKL/EMD). |
+| `barmesh_results_explorer` | Interactive MCP App with a **figure dropdown above the plot**; always leads with a standalone localhost URL + `ui_delivery`. |
 | `barmesh_send_feedback` | Send a short note or bug report to the Barivia team. |
 
 ### Figures and progress (0.5.2)
@@ -69,6 +69,11 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
   `plot_vol_all_meshes.png` shows volume fingerprints for every mesh in mesh_order.
 - **Learning curve:** every job produces `learning_curve.png` (QE by epoch) for training
   quality inspection; listed in the results explorer dropdown.
+- **Asymmetric mesh KL (`KL_asymmetric.png`):** pairwise ``D_{KL}(P\\|Q)`` heatmap —
+  above-diagonal coarse→fine, below-diagonal fine→coarse (meshes ordered coarse→fine).
+  Distinct from feature-plane `divergence_kl` (component association).
+- **Live ΔKL in training monitor:** panel SKL→ref mean/max curve (TE-panel sample) beside
+  the hit-grid; SOM batch-step axis labels (not FLooP) for regular mesh_convergence jobs.
 - **PDFs on demand:** publication vector PDFs are NOT generated by default. Render them
   after completion with `barmesh_results(action=render, format=pdf)`, then download with
   `barmesh_results(action=download, folder=...)` or `action=image`.
@@ -85,6 +90,8 @@ API key; otherwise the analysis calls return HTTP 403. Contact Barivia to enable
 
 ### Migration notes
 
+- **Feature-plane divergences (0.8.1):** Mesh jobs write `divergence_kl` / `feature_divergences.json` / `weights.json` (barsom-parallel). These measure association between SOM **component planes** — not mesh-vs-mesh fingerprint SKL/EMD (`KL_ref`, `EMD_*`). Refresh or add Wasserstein via `barmesh_results(action=feature_divergences)`.
+- **UI delivery + mesh_order (0.7.3+ / 0.8.0):** App tools emit structured `ui_delivery` and **always put the standalone viz URL first** (hosts may advertise MCP Apps without mounting widgets). Env: `BARIVIA_UI_DELIVERY` (`auto` \| `apps` \| `localhost` \| `inline`), `BARIVIA_VIZ_PORT`. Default mesh_order interleaves U/G at tied cell counts; Richardson warns on mixed topology families.
 - **Fixed-panel live TE (0.6.3 / barsom 0.20.4):** mid-training TE uses a fixed evaluation panel (`te_panel_size`; `te_inner_samples` alias). Curves stay on panel TE; monitors show **Panel TE** and **Map TE** separately — no snap-to-map on the curve tail.
 - **`barmesh_training_monitor` (0.5.3):** server-side blocking monitor with throttled snapshots — preferred after job submit instead of manual `barmesh_jobs(status)` loops. Equivalent to `barmesh_jobs(action=monitor)`.
 - **`send_feedback` → `barmesh_send_feedback` (0.3.0):** the feedback tool was renamed so it no longer collides with the `@barivia/barsom-mcp` tool of the same name when both servers are enabled in one client. Update any direct call sites; the behavior is unchanged.
@@ -110,4 +117,5 @@ Parquet staging is supported by the API but not yet exposed as an MCP upload for
 | `BARIVIA_FETCH_TIMEOUT_MS` | `60000` | Per-request timeout (raise for large uploads). |
 | `BARIVIA_WORKSPACE_ROOT` | workspace/cwd | Root for resolving relative `file_path` uploads. |
 | `BARIVIA_ENFORCE_WORKSPACE_SANDBOX` | `1` | Restrict uploads to the workspace; set `0` to allow absolute paths. |
-| `BARIVIA_VIZ_PORT` | ephemeral | Fixed localhost port for the `barmesh_results_explorer` standalone page (otherwise OS-assigned per session). |
+| `BARIVIA_VIZ_PORT` | ephemeral | Fixed localhost port for standalone App pages (otherwise OS-assigned per session). |
+| `BARIVIA_UI_DELIVERY` | `auto` | Client-capability override for App tools: `auto` \| `apps` \| `localhost` \| `inline`. Responses always lead with a standalone localhost URL. |

package/dist/audit.js

@@ -47,10 +47,12 @@ function extractIds(result) {
 function errorCodeFrom(err) {
     if (err && typeof err === "object") {
         const e = err;
+        if (e.errorCode)
+            return e.errorCode;
         if (e.httpStatus !== undefined)
             return `http_${e.httpStatus}`;
         const m = e.message ?? "";
-        const codeMatch = m.match(/error_code:\s*(\w+)/);
+        const codeMatch = m.match(/error_code[=:]\s*(\w+)/);
         if (codeMatch)
             return codeMatch[1];
     }

package/dist/deferred_feedback.js

@@ -0,0 +1,88 @@
+/**
+ * Local offline queue for barmesh_send_feedback when the API or object storage is down.
+ * Persists under ~/.barivia/deferred-feedback (or BARIVIA_FEEDBACK_QUEUE_DIR).
+ * Same layout as @barivia/barsom-mcp so both proxies share one queue directory.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+export function deferredFeedbackQueueDir() {
+    const override = process.env.BARIVIA_FEEDBACK_QUEUE_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(os.homedir(), ".barivia", "deferred-feedback");
+}
+async function ensureQueueDir() {
+    const dir = deferredFeedbackQueueDir();
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+function entryPath(dir, id) {
+    return path.join(dir, `${id}.json`);
+}
+export async function enqueueDeferredFeedback(product, body, lastError) {
+    const dir = await ensureQueueDir();
+    const id = randomUUID();
+    const entry = {
+        id,
+        product,
+        created_at: new Date().toISOString(),
+        body,
+        ...(lastError ? { last_error: lastError } : {}),
+    };
+    const filePath = entryPath(dir, id);
+    await fs.writeFile(filePath, JSON.stringify(entry, null, 2), "utf8");
+    return { id, path: filePath };
+}
+export async function listDeferredFeedback(product) {
+    const dir = deferredFeedbackQueueDir();
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(dir, name), "utf8");
+            const entry = JSON.parse(raw);
+            if (product && entry.product !== product)
+                continue;
+            out.push(entry);
+        }
+        catch {
+            /* skip corrupt */
+        }
+    }
+    out.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    return out;
+}
+/**
+ * Attempt to submit each queued entry via `submit`. Successful entries are deleted.
+ * Failures leave the file in place for a later retry.
+ */
+export async function flushDeferredFeedback(product, submit) {
+    const entries = await listDeferredFeedback(product);
+    let flushed = 0;
+    const errors = [];
+    const dir = deferredFeedbackQueueDir();
+    for (const entry of entries) {
+        try {
+            await submit(entry.body);
+            await fs.unlink(entryPath(dir, entry.id)).catch(() => undefined);
+            flushed += 1;
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    const remaining = (await listDeferredFeedback(product)).length;
+    return { flushed, remaining, errors };
+}

package/dist/figure_sections.js

@@ -24,6 +24,9 @@ export function figureSection(key) {
     }
     if (key === "learning_curve" || key.startsWith("plot_vol"))
         return "diagnostics";
+    // Feature-plane association heatmaps (barsom-parallel) — not mesh fingerprint KL/EMD.
+    if (key.startsWith("divergence_"))
+        return "component";
     if (key.startsWith("plot_"))
         return "component";
     return "diagnostics";
@@ -33,17 +36,22 @@ export const FIGURE_SORT_RANK = {
     overview_distances: 1,
     KL_ref: 10,
     KL_stepwise: 11,
-    EMD_ref: 12,
-    EMD_stepwise: 13,
-    learning_curve: 14,
+    KL_asymmetric: 12,
+    EMD_ref: 13,
+    EMD_stepwise: 14,
+    learning_curve: 15,
     plot_vol_all_meshes: 19,
     plot_vol_coarse_fine: 20,
+    divergence_kl: 28,
+    divergence_w1: 29,
 };
 export function sortRank(key) {
     if (key in FIGURE_SORT_RANK)
         return FIGURE_SORT_RANK[key];
     if (key.startsWith("plot_vol"))
         return 25;
+    if (key.startsWith("divergence_"))
+        return 28;
     if (key.startsWith("plot_"))
         return 30;
     return 50;

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as s,registerAppResource as o,RESOURCE_MIME_TYPE as n}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as t}from"./viz-server.js";import{API_KEY as i,CLIENT_VERSION as a,apiCall as c,apiRawCall as m,loadViewHtml as l,setVizPort as d,setClientSupportsMcpApps as p}from"./shared.js";import{registerGuideTool as h}from"./tools/guide.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerCfdTools as b}from"./tools/cfd.js";import{registerJobsTool as f}from"./tools/jobs.js";import{registerResultsTool as v}from"./tools/results.js";import{registerResultsExplorerTool as y,RESULTS_EXPLORER_URI as _}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as g,TRAINING_MONITOR_URI as w}from"./tools/training_monitor.js";import{registerFeedbackTool as j}from"./tools/feedback.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const i=new e({name:"barmesh",version:a},{instructions:"# Barivia barmesh — CFD mesh-convergence analytics\n\nSOM-based mesh-convergence verification: compare CFD meshes of a refinement study by the\nvolume-weighted distribution their cells form on a shared self-organizing map, plus\nclassical Richardson/GCI on scalar quantities.\n\n## Two tracks\n- barmesh_mesh_convergence: high-dimensional field comparison. Symmetric KL and\n  Wasserstein-1 (EMD) distances between each mesh's SOM fingerprint and a reference,\n  and between consecutive meshes. Decreasing, plateauing distances toward the finest\n  mesh indicate sufficiency. Complements (does not replace) numerical uncertainty analysis.\n- barmesh_richardson: classical grid-convergence index on scalar QoIs.\n\n## Workflow (read-only first)\n1. barmesh_guide_workflow — orient and confirm your plan includes CFD tools.\n2. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V).\n3. barmesh_datasets(action=upload) then preview.\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_training_monitor(job_id) — visual MCP App with live curves (default); barmesh_jobs(action=monitor) — headless blocking snapshots; or barmesh_jobs(status) for one-shot polls every 10-20s.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it."});o(i,_,_,{mimeType:n},async()=>{const e=await l("barmesh-results-explorer");return{contents:[{uri:_,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),o(i,w,w,{mimeType:n},async()=>{const e=await l("barmesh-training-monitor");return{contents:[{uri:w,mimeType:n,text:e??"<html><body>Training Monitor view not built yet. Run: npm run build:views</body></html>"}]}}),h(i),y(i),u(i),b(i),f(i),g(i),v(i),j(i);try{const e=await t(c,m,l);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const x=i.server;x.oninitialized=()=>{const e=x.getClientCapabilities(),r=s(e);p(!!r?.mimeTypes?.includes(n))};const I=new r;await i.connect(I),console.error(`barmesh-mcp ${a} ready (API: ${process.env.BARIVIA_API_URL??"https://api.barivia.se"})`)})().catch(e=>{console.error("Fatal error starting barmesh-mcp:",e),process.exit(1)});
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as r}from"@modelcontextprotocol/sdk/server/stdio.js";import{getUiCapability as s,registerAppResource as t,RESOURCE_MIME_TYPE as o}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as n}from"./viz-server.js";import{API_KEY as a,CLIENT_VERSION as i,apiCall as l,apiRawCall as c,loadViewHtml as m,setVizPort as d,setClientSupportsMcpApps as h}from"./shared.js";import{registerGuideTool as u}from"./tools/guide.js";import{registerDatasetsTool as p}from"./tools/datasets.js";import{registerCfdTools as b}from"./tools/cfd.js";import{registerJobsTool as f}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerResultsExplorerTool as y,RESULTS_EXPLORER_URI as v}from"./tools/barmesh_results_explorer.js";import{registerTrainingMonitorTool as g,TRAINING_MONITOR_URI as w}from"./tools/training_monitor.js";import{registerFeedbackTool as I}from"./tools/feedback.js";a||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));(async function(){const a=new e({name:"barmesh",version:i},{instructions:"# Barivia barmesh — CFD mesh-convergence analytics\n\nSOM-based mesh-convergence verification: compare CFD meshes of a refinement study by the\nvolume-weighted distribution their cells form on a shared self-organizing map, plus\nclassical Richardson/GCI on scalar quantities.\n\n## Two tracks\n- barmesh_mesh_convergence: high-dimensional field comparison. Symmetric KL and\n  Wasserstein-1 (EMD) distances between each mesh's SOM fingerprint and a reference,\n  and between consecutive meshes. Decreasing, plateauing distances toward the finest\n  mesh indicate sufficiency. Complements (does not replace) numerical uncertainty analysis.\n- barmesh_richardson: classical grid-convergence index on scalar QoIs.\n\n## Workflow (read-only first)\n1. barmesh_guide_workflow — orient and confirm your plan includes CFD tools.\n2. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V).\n3. barmesh_datasets(action=upload) then preview (optional description/tags for inventory).\n4. barmesh_mesh_convergence (and/or barmesh_richardson) — returns a job id.\n5. barmesh_training_monitor(job_id) — visual MCP App with live curves (default); barmesh_jobs(action=monitor) — headless blocking snapshots; or barmesh_jobs(status) for one-shot polls every 10-20s.\n6. barmesh_results(action=get) — distances, convergence reading, and figures; then\n   barmesh_results_explorer(job_id) to browse every figure interactively.\n\n## Org inventory recipe\n- Prefer `barmesh_jobs(action=inventory)` for a markdown datasets+jobs overview.\n- Or compose `barmesh_datasets(list)` + `barmesh_jobs(action=list, limit=50)` (page with `cursor`; filter with `status`/`job_type`/`has_results=true` for a results catalog).\n- Set `description`+`tags` on upload/submit/update so duplicates stay navigable. List is slim by default (no fat params).\n\n## UI delivery (barmesh_training_monitor, barmesh_results_explorer)\n\nHosts vary: some embed MCP Apps; others list ui:// but never mount them (expected on some Cursor builds). Tool results always lead with a standalone localhost URL and a structured ui_delivery block (delivery, urls, hint_for_agent) — follow hint_for_agent without user prompting.\n\n- Surface the standalone URL as a clickable markdown link. Do not bury it after metrics.\n- Env: BARIVIA_UI_DELIVERY=auto|apps|localhost|inline; BARIVIA_VIZ_PORT pins the viz port across restarts.\n- Standalone pages cross-link training monitor ↔ results explorer for the same job_id.\n\nThese tools are gated by the 'cfd' entitlement; analysis calls return 403 if your plan\ndoes not include it.\n\n## API briefly unavailable (demos)\nIf barmesh_jobs / barmesh_results / barmesh_send_feedback (or any tool) reports the mesh analysis\nAPI temporarily unavailable: say so in one calm line, do not paste HTML/502 pages, and pause\nafter the proxy's burst retries (3 tries ~2s apart; then retry_after_sec≈30). Figures already\ndownloaded stay usable. Keep talking about the last good distances, GCI CSV, and figures —\ndegrade to \"review what we have\", not \"everything failed\". Suggest a later retry for new jobs\nor feedback.\n\n## Outages / feedback\n- barmesh_api_health probes GET /health + /ready (no R2). Use when tools fail with api_unreachable.\n- barmesh_send_feedback queues drafts under ~/.barivia/deferred-feedback when the API/gateway\n  is down and flushes them on the next successful call (shared directory with barsom send_feedback).\n- API errors are slim structured lines (error_code, cause, request_id, retry_after_sec) — never raw Cloudflare HTML."});t(a,v,v,{mimeType:o},async()=>{const e=await m("barmesh-results-explorer");return{contents:[{uri:v,mimeType:o,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),t(a,w,w,{mimeType:o},async()=>{const e=await m("barmesh-training-monitor");return{contents:[{uri:w,mimeType:o,text:e??"<html><body>Training Monitor view not built yet. Run: npm run build:views</body></html>"}]}}),u(a),y(a),p(a),b(a),f(a),g(a),_(a),I(a);try{const e=await n(l,c,m);d(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("barmesh viz server failed to start:",e)}const j=a.server;j.oninitialized=()=>{const e=j.getClientCapabilities(),r=s(e);h(!!r?.mimeTypes?.includes(o))};const k=new r;await a.connect(k),console.error(`barmesh-mcp ${i} ready (API: ${process.env.BARIVIA_API_URL??"https://api.barivia.se"})`)})().catch(e=>{console.error("Fatal error starting barmesh-mcp:",e),process.exit(1)});

package/dist/inventory_format.js

@@ -0,0 +1,69 @@
+/** Shared markdown inventory formatting for barmesh list/inventory. */
+export function formatTags(tags) {
+    if (!Array.isArray(tags) || tags.length === 0)
+        return "";
+    return tags.map((t) => String(t)).filter(Boolean).join(", ");
+}
+export function formatDatasetInventoryLine(ds) {
+    const id = String(ds.id ?? "");
+    const name = String(ds.name ?? "");
+    const rows = ds.rows != null ? Number(ds.rows) : "?";
+    const cols = ds.cols != null ? Number(ds.cols) : "?";
+    const st = ds.status != null ? String(ds.status) : "ready";
+    const statusBit = st !== "ready" ? ` | status=${st}` : "";
+    const desc = ds.description != null && String(ds.description).trim() !== ""
+        ? ` — ${String(ds.description).trim()}`
+        : "";
+    const tags = formatTags(ds.tags);
+    const tagsBit = tags ? ` [${tags}]` : "";
+    return `${name} (${id}) — ${rows}×${cols}${statusBit}${tagsBit}${desc}`;
+}
+export function formatJobInventoryLine(job) {
+    const id = String(job.id ?? "");
+    const st = String(job.status ?? "");
+    const label = job.label != null && job.label !== "" ? String(job.label) : null;
+    const jt = job.job_type != null ? String(job.job_type) : "?";
+    const ds = job.dataset_id != null ? String(job.dataset_id) : "";
+    const created = job.created_at != null ? String(job.created_at) : "";
+    const result = job.result_ref != null && String(job.result_ref) !== "" ? "yes" : "no";
+    const tags = formatTags(job.tags);
+    const tagsBit = tags ? ` [${tags}]` : "";
+    const desc = job.description != null && String(job.description).trim() !== ""
+        ? ` — ${String(job.description).trim()}`
+        : "";
+    const head = label ? `${label} (id: ${id})` : `id: ${id}`;
+    return `${head} — ${st} | type=${jt} | dataset=${ds} | created=${created} | result=${result}${tagsBit}${desc}`;
+}
+export function extractJobsList(data) {
+    if (Array.isArray(data)) {
+        return { jobs: data, next_cursor: null };
+    }
+    if (data && typeof data === "object") {
+        const obj = data;
+        const jobs = Array.isArray(obj.jobs) ? obj.jobs : [];
+        const next = obj.next_cursor != null && String(obj.next_cursor) !== ""
+            ? String(obj.next_cursor)
+            : null;
+        return { jobs, next_cursor: next };
+    }
+    return { jobs: [], next_cursor: null };
+}
+export function buildJobsListQuery(opts) {
+    const qs = new URLSearchParams();
+    if (opts.dataset_id)
+        qs.set("dataset_id", opts.dataset_id);
+    if (opts.status)
+        qs.set("status", opts.status);
+    if (opts.job_type)
+        qs.set("job_type", opts.job_type);
+    if (opts.has_results)
+        qs.set("has_results", "true");
+    if (opts.limit != null)
+        qs.set("limit", String(opts.limit));
+    if (opts.cursor)
+        qs.set("cursor", opts.cursor);
+    if (opts.fields)
+        qs.set("fields", opts.fields);
+    const s = qs.toString();
+    return s ? `/v1/jobs?${s}` : "/v1/jobs";
+}

package/dist/richardson_results.js

@@ -0,0 +1,35 @@
+/** Format barmesh_results(get) text for cfd_richardson_gci jobs. */
+export function formatRichardsonResultsSummary(jobId, data, summary) {
+    const label = data.label != null && data.label !== "" ? String(data.label) : null;
+    const header = label
+        ? `Richardson/GCI results for ${label} (job_id: ${jobId})`
+        : `Richardson/GCI results for job_id: ${jobId}`;
+    const qois = summary.qoi_columns ?? [];
+    const meshOrder = summary.mesh_order_fine_to_coarse ?? [];
+    const fmt = (v) => (typeof v === "number" && Number.isFinite(v) ? v.toFixed(4) : String(v ?? "N/A"));
+    const results = summary.results ?? {};
+    const lines = [
+        header,
+        `Meshes (fine→coarse): ${meshOrder.length > 0 ? meshOrder.join(" → ") : "N/A"}`,
+        `Safety factor Fs: ${fmt(summary.safety_factor ?? 1.25)} | h source: ${String(summary.h_source ?? "n_cells_column")}`,
+    ];
+    const warning = summary.topology_warning;
+    if (typeof warning === "string" && warning.length > 0) {
+        lines.push(`\n⚠ Topology: ${warning}`);
+    }
+    for (const q of qois) {
+        const triplets = results[q] ?? [];
+        if (triplets.length === 0)
+            continue;
+        lines.push(`\nQoI ${q} (${triplets.length} triplet${triplets.length === 1 ? "" : "s"}):`);
+        for (const t of triplets) {
+            const mono = t.monotonic === true ? "monotonic" : t.monotonic === false ? "non-monotonic" : "monotonicity n/a";
+            lines.push(`  ${String(t.triplet ?? "?")}: p=${fmt(t.p)} f_ext=${fmt(t.f_ext)} GCI_fine=${fmt(t.gci_fine_pct)}% (${mono})`);
+        }
+    }
+    lines.push("\nFull table: richardson_gci.csv (one row per triplet per QoI).", "Advisory: classical GCI complements SOM fingerprint distances (barmesh_mesh_convergence).", "Use barmesh_results(action=download, figures=none, include_json=true) to save richardson_gci.csv locally.");
+    return lines.join("\n");
+}
+export function isRichardsonJob(summary) {
+    return String(summary.job_type ?? "") === "cfd_richardson_gci";
+}