homegraph 1.1.2 → 1.1.3

package/scripts/agent-eval/seq-matrix.mjs

@@ -1,137 +1,137 @@
-#!/usr/bin/env node
-// Mine the surviving A/B stream-json logs (/tmp/ab-matrix/<Cell>/run-headless-*.jsonl)
-// for what the aggregate matrix can't see: the call SEQUENCE and per-call output SIZE.
-//
-// Answers three questions:
-//   1. Trace adoption — on a flow question, does the with-arm actually call homegraph_trace?
-//   2. Payload size vs repo size — is trace path-scoped (tiny, size-independent) while
-//      explore is breadth-scoped (grows with the repo / over-returns on small repos)?
-//   3. Round-trips — num_turns with vs without (the real wall-clock driver).
-//
-// Usage: node scripts/agent-eval/seq-matrix.mjs [/tmp/ab-matrix]
-import { readFileSync, readdirSync, existsSync } from 'fs';
-import { join } from 'path';
-
-const AB = process.argv[2] || '/tmp/ab-matrix';
-const MD = new URL('../../docs/benchmarks/homegraph-ab-matrix.md', import.meta.url).pathname;
-
-// repo -> {lang,size,files} from the published matrix table
-const repoMeta = {};
-if (existsSync(MD)) for (const line of readFileSync(MD, 'utf8').split('\n')) {
-  const m = line.match(/^\|\s*([^|]+?)\s*\|\s*(S|M|L)\s*\|\s*`([^`]+)`\s*\|\s*(\d+)\s*\|/);
-  if (m) repoMeta[m[3]] = { lang: m[1].trim(), size: m[2], files: +m[4] };
-}
-
-const cgShort = (n) => n.replace('mcp__homegraph__homegraph_', '').replace('mcp__homegraph__', '');
-const tag = (n) => n === 'Read' ? 'R' : n === 'Grep' ? 'G' : n === 'Glob' ? 'Gl'
-  : n === 'Bash' ? 'B' : n === 'Task' ? 'Ag' : n === 'ToolSearch' ? 'TS'
-  : n.includes('homegraph') ? cgShort(n) : n;
-
-function parse(file) {
-  if (!existsSync(file)) return null;
-  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
-  const calls = []; let result = null, initCg = 0;
-  for (const l of lines) {
-    let ev; try { ev = JSON.parse(l); } catch { continue; }
-    if (ev.type === 'system' && ev.subtype === 'init') initCg = (ev.tools || []).filter(t => /homegraph/.test(t)).length;
-    if (ev.type === 'assistant') for (const b of (ev.message?.content || [])) if (b.type === 'tool_use') {
-      const i = b.input || {};
-      const q = i.query ?? i.symbol ?? i.task ?? (i.from && i.to ? `${i.from}->${i.to}` : (i.file_path || i.command || ''));
-      calls.push({ id: b.id, name: b.name, q: String(q ?? '').slice(0, 38), out: 0 });
-    }
-    if (ev.type === 'user') for (const b of (ev.message?.content || [])) if (b.type === 'tool_result') {
-      const c = b.content;
-      const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => x?.text || '').join('') : '';
-      const call = calls.find(k => k.id === b.tool_use_id); if (call) call.out = txt.length;
-    }
-    if (ev.type === 'result') result = ev;
-  }
-  const cg = calls.filter(c => c.name.includes('homegraph'));
-  const perTool = {};
-  for (const c of cg) { const k = cgShort(c.name); (perTool[k] ??= { n: 0, out: 0 }); perTool[k].n++; perTool[k].out += c.out; }
-  const traceIdx = cg.findIndex(c => c.name.includes('trace'));
-  const u = result?.usage || {};
-  return {
-    initCg, cg, perTool,
-    cgSeq: cg.map(c => cgShort(c.name)),
-    seq: calls.map(c => tag(c.name)),
-    reads: calls.filter(c => c.name === 'Read').length,
-    greps: calls.filter(c => c.name === 'Grep').length,
-    cgOut: cg.reduce((s, c) => s + c.out, 0),
-    traceUsed: traceIdx >= 0,
-    afterTrace: traceIdx >= 0 ? cg.slice(traceIdx + 1).map(c => cgShort(c.name)) : null,
-    turns: result?.num_turns ?? null,
-    dur: result?.duration_ms ? Math.round(result.duration_ms / 1000) : null,
-    cost: result?.total_cost_usd || 0,
-  };
-}
-
-const cells = [];
-for (const d of readdirSync(AB)) {
-  const dir = join(AB, d);
-  if (!existsSync(join(dir, 'run-headless-with.jsonl'))) continue;
-  const log = existsSync(join(AB, d + '.log')) ? readFileSync(join(AB, d + '.log'), 'utf8') : '';
-  const repo = (log.match(/repo:\s*\S*\/([^\s/]+)/) || [])[1] || d;
-  const question = (log.match(/question:\s*(.+)/) || [])[1] || '';
-  cells.push({ cell: d, repo, question, ...(repoMeta[repo] || {}),
-    with: parse(join(dir, 'run-headless-with.jsonl')),
-    without: parse(join(dir, 'run-headless-without.jsonl')) });
-}
-cells.sort((a, b) => (a.files || 0) - (b.files || 0));
-
-const k = (n) => (n / 1000).toFixed(1);
-const pad = (s, n) => String(s).padEnd(n);
-
-// ---- per-cell sequence table ----
-console.log('\n=== PER-CELL: with-arm homegraph sequence + payload (sorted by repo size) ===');
-console.log(pad('repo', 22), pad('files', 6), 'trace', pad('cg-call sequence', 40), pad('cgOutK', 7), 'turns(w/wo)');
-for (const c of cells) {
-  const w = c.with;
-  console.log(
-    pad(c.repo, 22), pad(c.files ?? '?', 6),
-    pad(w.traceUsed ? 'YES' : 'no', 5),
-    pad(w.cgSeq.join(',') || '(none)', 40),
-    pad(k(w.cgOut), 7),
-    `${w.turns}/${c.without?.turns}`,
-  );
-}
-
-// ---- trace adoption ----
-const flow = cells; // every matrix question is a canonical flow question by design
-const used = flow.filter(c => c.with.traceUsed);
-console.log(`\n=== TRACE ADOPTION (all ${flow.length} cells are flow questions) ===`);
-console.log(`trace called in ${used.length}/${flow.length} cells`);
-console.log('used trace:', used.map(c => c.repo).join(', ') || '(none)');
-if (used.length) console.log('after-trace follow-ups:', used.map(c => `${c.repo}[${c.with.afterTrace.join(',') || 'none'}]`).join('  '));
-
-// ---- payload size by repo-size tier ----
-const tier = (f) => f < 200 ? 'S(<200)' : f < 2000 ? 'M(<2000)' : 'L(>=2000)';
-const byTier = {};
-for (const c of cells) { (byTier[tier(c.files || 0)] ??= []).push(c.with.cgOut); }
-console.log('\n=== with-arm TOTAL homegraph payload by repo-size tier ===');
-for (const t of ['S(<200)', 'M(<2000)', 'L(>=2000)']) {
-  const a = byTier[t] || []; if (!a.length) continue;
-  const avg = a.reduce((s, x) => s + x, 0) / a.length;
-  console.log(`  ${pad(t, 10)} n=${a.length}  avg cgOut=${k(avg)}K  range ${k(Math.min(...a))}-${k(Math.max(...a))}K`);
-}
-
-// ---- per-tool usage + avg payload (breadth vs path evidence) ----
-const tot = {};
-for (const c of cells) for (const [name, v] of Object.entries(c.with.perTool)) {
-  (tot[name] ??= { n: 0, out: 0 }); tot[name].n += v.n; tot[name].out += v.out;
-}
-console.log('\n=== homegraph tool usage across all cells (n calls, avg payload/call) ===');
-for (const [name, v] of Object.entries(tot).sort((a, b) => b[1].n - a[1].n)) {
-  console.log(`  ${pad(name, 10)} calls=${pad(v.n, 4)} avg=${k(v.out / v.n)}K/call  total=${k(v.out)}K`);
-}
-
-// ---- round-trips ----
-const sum = (arr, f) => arr.reduce((s, x) => s + (f(x) || 0), 0);
-const wTurns = sum(cells, c => c.with.turns), woTurns = sum(cells, c => c.without?.turns);
-const wCalls = sum(cells, c => c.with.cg.length);
-const tsAll = cells.every(c => c.with.seq[0] === 'TS');
-console.log('\n=== ROUND-TRIPS ===');
-console.log(`turns: with=${wTurns}  without=${woTurns}  (${((1 - wTurns / woTurns) * 100).toFixed(0)}% fewer with)`);
-console.log(`avg turns/cell: with=${(wTurns / cells.length).toFixed(1)}  without=${(woTurns / cells.length).toFixed(1)}`);
-console.log(`total homegraph calls=${wCalls} (avg ${(wCalls / cells.length).toFixed(1)}/cell)`);
-console.log(`every with-arm opens with a ToolSearch round-trip (deferred tools): ${tsAll ? 'YES — 1 fixed tax/run' : 'no'}`);
+#!/usr/bin/env node
+// Mine the surviving A/B stream-json logs (/tmp/ab-matrix/<Cell>/run-headless-*.jsonl)
+// for what the aggregate matrix can't see: the call SEQUENCE and per-call output SIZE.
+//
+// Answers three questions:
+//   1. Trace adoption — on a flow question, does the with-arm actually call homegraph_trace?
+//   2. Payload size vs repo size — is trace path-scoped (tiny, size-independent) while
+//      explore is breadth-scoped (grows with the repo / over-returns on small repos)?
+//   3. Round-trips — num_turns with vs without (the real wall-clock driver).
+//
+// Usage: node scripts/agent-eval/seq-matrix.mjs [/tmp/ab-matrix]
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const AB = process.argv[2] || '/tmp/ab-matrix';
+const MD = new URL('../../docs/benchmarks/homegraph-ab-matrix.md', import.meta.url).pathname;
+
+// repo -> {lang,size,files} from the published matrix table
+const repoMeta = {};
+if (existsSync(MD)) for (const line of readFileSync(MD, 'utf8').split('\n')) {
+  const m = line.match(/^\|\s*([^|]+?)\s*\|\s*(S|M|L)\s*\|\s*`([^`]+)`\s*\|\s*(\d+)\s*\|/);
+  if (m) repoMeta[m[3]] = { lang: m[1].trim(), size: m[2], files: +m[4] };
+}
+
+const cgShort = (n) => n.replace('mcp__homegraph__homegraph_', '').replace('mcp__homegraph__', '');
+const tag = (n) => n === 'Read' ? 'R' : n === 'Grep' ? 'G' : n === 'Glob' ? 'Gl'
+  : n === 'Bash' ? 'B' : n === 'Task' ? 'Ag' : n === 'ToolSearch' ? 'TS'
+  : n.includes('homegraph') ? cgShort(n) : n;
+
+function parse(file) {
+  if (!existsSync(file)) return null;
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const calls = []; let result = null, initCg = 0;
+  for (const l of lines) {
+    let ev; try { ev = JSON.parse(l); } catch { continue; }
+    if (ev.type === 'system' && ev.subtype === 'init') initCg = (ev.tools || []).filter(t => /homegraph/.test(t)).length;
+    if (ev.type === 'assistant') for (const b of (ev.message?.content || [])) if (b.type === 'tool_use') {
+      const i = b.input || {};
+      const q = i.query ?? i.symbol ?? i.task ?? (i.from && i.to ? `${i.from}->${i.to}` : (i.file_path || i.command || ''));
+      calls.push({ id: b.id, name: b.name, q: String(q ?? '').slice(0, 38), out: 0 });
+    }
+    if (ev.type === 'user') for (const b of (ev.message?.content || [])) if (b.type === 'tool_result') {
+      const c = b.content;
+      const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => x?.text || '').join('') : '';
+      const call = calls.find(k => k.id === b.tool_use_id); if (call) call.out = txt.length;
+    }
+    if (ev.type === 'result') result = ev;
+  }
+  const cg = calls.filter(c => c.name.includes('homegraph'));
+  const perTool = {};
+  for (const c of cg) { const k = cgShort(c.name); (perTool[k] ??= { n: 0, out: 0 }); perTool[k].n++; perTool[k].out += c.out; }
+  const traceIdx = cg.findIndex(c => c.name.includes('trace'));
+  const u = result?.usage || {};
+  return {
+    initCg, cg, perTool,
+    cgSeq: cg.map(c => cgShort(c.name)),
+    seq: calls.map(c => tag(c.name)),
+    reads: calls.filter(c => c.name === 'Read').length,
+    greps: calls.filter(c => c.name === 'Grep').length,
+    cgOut: cg.reduce((s, c) => s + c.out, 0),
+    traceUsed: traceIdx >= 0,
+    afterTrace: traceIdx >= 0 ? cg.slice(traceIdx + 1).map(c => cgShort(c.name)) : null,
+    turns: result?.num_turns ?? null,
+    dur: result?.duration_ms ? Math.round(result.duration_ms / 1000) : null,
+    cost: result?.total_cost_usd || 0,
+  };
+}
+
+const cells = [];
+for (const d of readdirSync(AB)) {
+  const dir = join(AB, d);
+  if (!existsSync(join(dir, 'run-headless-with.jsonl'))) continue;
+  const log = existsSync(join(AB, d + '.log')) ? readFileSync(join(AB, d + '.log'), 'utf8') : '';
+  const repo = (log.match(/repo:\s*\S*\/([^\s/]+)/) || [])[1] || d;
+  const question = (log.match(/question:\s*(.+)/) || [])[1] || '';
+  cells.push({ cell: d, repo, question, ...(repoMeta[repo] || {}),
+    with: parse(join(dir, 'run-headless-with.jsonl')),
+    without: parse(join(dir, 'run-headless-without.jsonl')) });
+}
+cells.sort((a, b) => (a.files || 0) - (b.files || 0));
+
+const k = (n) => (n / 1000).toFixed(1);
+const pad = (s, n) => String(s).padEnd(n);
+
+// ---- per-cell sequence table ----
+console.log('\n=== PER-CELL: with-arm homegraph sequence + payload (sorted by repo size) ===');
+console.log(pad('repo', 22), pad('files', 6), 'trace', pad('cg-call sequence', 40), pad('cgOutK', 7), 'turns(w/wo)');
+for (const c of cells) {
+  const w = c.with;
+  console.log(
+    pad(c.repo, 22), pad(c.files ?? '?', 6),
+    pad(w.traceUsed ? 'YES' : 'no', 5),
+    pad(w.cgSeq.join(',') || '(none)', 40),
+    pad(k(w.cgOut), 7),
+    `${w.turns}/${c.without?.turns}`,
+  );
+}
+
+// ---- trace adoption ----
+const flow = cells; // every matrix question is a canonical flow question by design
+const used = flow.filter(c => c.with.traceUsed);
+console.log(`\n=== TRACE ADOPTION (all ${flow.length} cells are flow questions) ===`);
+console.log(`trace called in ${used.length}/${flow.length} cells`);
+console.log('used trace:', used.map(c => c.repo).join(', ') || '(none)');
+if (used.length) console.log('after-trace follow-ups:', used.map(c => `${c.repo}[${c.with.afterTrace.join(',') || 'none'}]`).join('  '));
+
+// ---- payload size by repo-size tier ----
+const tier = (f) => f < 200 ? 'S(<200)' : f < 2000 ? 'M(<2000)' : 'L(>=2000)';
+const byTier = {};
+for (const c of cells) { (byTier[tier(c.files || 0)] ??= []).push(c.with.cgOut); }
+console.log('\n=== with-arm TOTAL homegraph payload by repo-size tier ===');
+for (const t of ['S(<200)', 'M(<2000)', 'L(>=2000)']) {
+  const a = byTier[t] || []; if (!a.length) continue;
+  const avg = a.reduce((s, x) => s + x, 0) / a.length;
+  console.log(`  ${pad(t, 10)} n=${a.length}  avg cgOut=${k(avg)}K  range ${k(Math.min(...a))}-${k(Math.max(...a))}K`);
+}
+
+// ---- per-tool usage + avg payload (breadth vs path evidence) ----
+const tot = {};
+for (const c of cells) for (const [name, v] of Object.entries(c.with.perTool)) {
+  (tot[name] ??= { n: 0, out: 0 }); tot[name].n += v.n; tot[name].out += v.out;
+}
+console.log('\n=== homegraph tool usage across all cells (n calls, avg payload/call) ===');
+for (const [name, v] of Object.entries(tot).sort((a, b) => b[1].n - a[1].n)) {
+  console.log(`  ${pad(name, 10)} calls=${pad(v.n, 4)} avg=${k(v.out / v.n)}K/call  total=${k(v.out)}K`);
+}
+
+// ---- round-trips ----
+const sum = (arr, f) => arr.reduce((s, x) => s + (f(x) || 0), 0);
+const wTurns = sum(cells, c => c.with.turns), woTurns = sum(cells, c => c.without?.turns);
+const wCalls = sum(cells, c => c.with.cg.length);
+const tsAll = cells.every(c => c.with.seq[0] === 'TS');
+console.log('\n=== ROUND-TRIPS ===');
+console.log(`turns: with=${wTurns}  without=${woTurns}  (${((1 - wTurns / woTurns) * 100).toFixed(0)}% fewer with)`);
+console.log(`avg turns/cell: with=${(wTurns / cells.length).toFixed(1)}  without=${(woTurns / cells.length).toFixed(1)}`);
+console.log(`total homegraph calls=${wCalls} (avg ${(wCalls / cells.length).toFixed(1)}/cell)`);
+console.log(`every with-arm opens with a ToolSearch round-trip (deferred tools): ${tsAll ? 'YES — 1 fixed tax/run' : 'no'}`);

package/scripts/build-bundle.sh

@@ -1,118 +1,118 @@
-#!/usr/bin/env bash
-#
-# Build a self-contained HomeGraph bundle: an official Node runtime + the
-# compiled app + its production deps, so HomeGraph runs with NO system Node and
-# NO native build — node:sqlite is built into the bundled Node. One archive per
-# platform.
-#
-# Because dropping better-sqlite3 left zero native addons, the recipe is pure
-# file-packaging (download the target's Node, copy the app, archive) — so any
-# platform's bundle can be built on any OS. No cross-compile, no native runners.
-#
-# Usage:
-#   scripts/build-bundle.sh <target> [node-version]
-#     target:        darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
-#                  | win32-x64 | win32-arm64
-#     node-version:  e.g. v24.16.0 (default below; pin for reproducible builds)
-#
-# Output:
-#   unix:    release/homegraph-<target>.tar.gz   (launcher: bin/homegraph)
-#   windows: release/homegraph-<target>.zip      (launcher: bin/homegraph.cmd)
-set -euo pipefail
-
-TARGET="${1:?usage: build-bundle.sh <target> [node-version]}"
-NODE_VERSION="${2:-v24.16.0}"
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OUT="$ROOT/release"
-WORK="$(mktemp -d)"
-trap 'rm -rf "$WORK"' EXIT
-
-ARCH="${TARGET##*-}"   # x64 | arm64
-OSFAM="${TARGET%-*}"   # darwin | linux | win32
-
-echo "[bundle] target=${TARGET} node=${NODE_VERSION}"
-
-# 1. Download + extract the official Node runtime for the target platform.
-if [ "$OSFAM" = "win32" ]; then
-  NODE_DIST="node-${NODE_VERSION}-win-${ARCH}"
-  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.zip"
-  echo "[bundle] downloading ${NODE_URL}"
-  curl -fsSL "$NODE_URL" -o "$WORK/node.zip"
-  if command -v unzip >/dev/null 2>&1; then
-    unzip -q "$WORK/node.zip" -d "$WORK"
-  else
-    tar -xf "$WORK/node.zip" -C "$WORK"   # bsdtar can read zip
-  fi
-  NODE_BIN="$WORK/${NODE_DIST}/node.exe"
-else
-  NODE_DIST="node-${NODE_VERSION}-${TARGET}"
-  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.tar.gz"
-  echo "[bundle] downloading ${NODE_URL}"
-  curl -fsSL "$NODE_URL" -o "$WORK/node.tar.gz"
-  tar -xzf "$WORK/node.tar.gz" -C "$WORK"
-  NODE_BIN="$WORK/${NODE_DIST}/bin/node"
-fi
-[ -f "$NODE_BIN" ] || { echo "[bundle] error: node binary not found ($NODE_BIN)" >&2; exit 1; }
-
-# 2. Build the app (compiled JS + copied wasm/schema assets).
-echo "[bundle] building app"
-( cd "$ROOT" && npm run build >/dev/null )
-
-# 3. Stage: app + production-only deps (pure JS/wasm → portable across platforms).
-STAGE="$WORK/homegraph-${TARGET}"
-mkdir -p "$STAGE/lib" "$STAGE/bin"
-cp -R "$ROOT/dist" "$STAGE/lib/dist"
-cp "$ROOT/package.json" "$ROOT/package-lock.json" "$STAGE/lib/"
-echo "[bundle] installing production dependencies"
-( cd "$STAGE/lib" && npm ci --omit=dev --ignore-scripts >/dev/null 2>&1 )
-rm -f "$STAGE/lib/package-lock.json"
-
-# 4. Vendored Node + launcher (the launcher uses the bundled Node by relative
-#    path, so no system Node is ever needed).
-#
-# `--liftoff-only`: keep tree-sitter's large WASM grammars on V8's Liftoff
-# baseline compiler so they never reach the turboshaft optimizing tier, whose
-# per-compilation Zone arena OOMs the whole process (`Fatal process out of
-# memory: Zone`) on Node >= 22 — even with tens of GB free. The flag is read at
-# V8 engine init so it must be on node's command line; the parse worker inherits
-# it. See issues #293/#298 and src/extraction/wasm-runtime-flags.ts. (The CLI
-# also self-relaunches with this flag when launched without it, so non-bundled
-# runs are covered too; passing it here avoids that extra spawn.)
-if [ "$OSFAM" = "win32" ]; then
-  cp "$NODE_BIN" "$STAGE/node.exe"
-  printf '@"%%~dp0..\\node.exe" --liftoff-only "%%~dp0..\\lib\\dist\\bin\\homegraph.js" %%*\r\n' \
-    > "$STAGE/bin/homegraph.cmd"
-else
-  cp "$NODE_BIN" "$STAGE/node"
-  cat > "$STAGE/bin/homegraph" <<'LAUNCH'
-#!/bin/sh
-# Resolve symlinks (e.g. the ~/.local/bin/homegraph link install.sh creates) so
-# we find the real bundle dir, not the symlink's location.
-SELF="$0"
-while [ -L "$SELF" ]; do
-  target="$(readlink "$SELF")"
-  case "$target" in
-    /*) SELF="$target" ;;
-    *) SELF="$(dirname "$SELF")/$target" ;;
-  esac
-done
-DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
-# --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
-exec "$DIR/node" --liftoff-only "$DIR/lib/dist/bin/homegraph.js" "$@"
-LAUNCH
-  chmod +x "$STAGE/bin/homegraph"
-fi
-
-# 5. Archive (.zip for Windows, .tar.gz otherwise).
-mkdir -p "$OUT"
-if [ "$OSFAM" = "win32" ]; then
-  ARCHIVE="$OUT/homegraph-${TARGET}.zip"
-  rm -f "$ARCHIVE"
-  ( cd "$WORK" && zip -rqX "$ARCHIVE" "homegraph-${TARGET}" )
-else
-  ARCHIVE="$OUT/homegraph-${TARGET}.tar.gz"
-  # --no-xattrs: don't embed macOS xattrs that make GNU tar warn on Linux.
-  tar --no-xattrs -czf "$ARCHIVE" -C "$WORK" "homegraph-${TARGET}"
-fi
-echo "[bundle] wrote ${ARCHIVE} ($(du -h "$ARCHIVE" | cut -f1))"
+#!/usr/bin/env bash
+#
+# Build a self-contained HomeGraph bundle: an official Node runtime + the
+# compiled app + its production deps, so HomeGraph runs with NO system Node and
+# NO native build — node:sqlite is built into the bundled Node. One archive per
+# platform.
+#
+# Because dropping better-sqlite3 left zero native addons, the recipe is pure
+# file-packaging (download the target's Node, copy the app, archive) — so any
+# platform's bundle can be built on any OS. No cross-compile, no native runners.
+#
+# Usage:
+#   scripts/build-bundle.sh <target> [node-version]
+#     target:        darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
+#                  | win32-x64 | win32-arm64
+#     node-version:  e.g. v24.16.0 (default below; pin for reproducible builds)
+#
+# Output:
+#   unix:    release/homegraph-<target>.tar.gz   (launcher: bin/homegraph)
+#   windows: release/homegraph-<target>.zip      (launcher: bin/homegraph.cmd)
+set -euo pipefail
+
+TARGET="${1:?usage: build-bundle.sh <target> [node-version]}"
+NODE_VERSION="${2:-v24.16.0}"
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUT="$ROOT/release"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+ARCH="${TARGET##*-}"   # x64 | arm64
+OSFAM="${TARGET%-*}"   # darwin | linux | win32
+
+echo "[bundle] target=${TARGET} node=${NODE_VERSION}"
+
+# 1. Download + extract the official Node runtime for the target platform.
+if [ "$OSFAM" = "win32" ]; then
+  NODE_DIST="node-${NODE_VERSION}-win-${ARCH}"
+  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.zip"
+  echo "[bundle] downloading ${NODE_URL}"
+  curl -fsSL "$NODE_URL" -o "$WORK/node.zip"
+  if command -v unzip >/dev/null 2>&1; then
+    unzip -q "$WORK/node.zip" -d "$WORK"
+  else
+    tar -xf "$WORK/node.zip" -C "$WORK"   # bsdtar can read zip
+  fi
+  NODE_BIN="$WORK/${NODE_DIST}/node.exe"
+else
+  NODE_DIST="node-${NODE_VERSION}-${TARGET}"
+  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.tar.gz"
+  echo "[bundle] downloading ${NODE_URL}"
+  curl -fsSL "$NODE_URL" -o "$WORK/node.tar.gz"
+  tar -xzf "$WORK/node.tar.gz" -C "$WORK"
+  NODE_BIN="$WORK/${NODE_DIST}/bin/node"
+fi
+[ -f "$NODE_BIN" ] || { echo "[bundle] error: node binary not found ($NODE_BIN)" >&2; exit 1; }
+
+# 2. Build the app (compiled JS + copied wasm/schema assets).
+echo "[bundle] building app"
+( cd "$ROOT" && npm run build >/dev/null )
+
+# 3. Stage: app + production-only deps (pure JS/wasm → portable across platforms).
+STAGE="$WORK/homegraph-${TARGET}"
+mkdir -p "$STAGE/lib" "$STAGE/bin"
+cp -R "$ROOT/dist" "$STAGE/lib/dist"
+cp "$ROOT/package.json" "$ROOT/package-lock.json" "$STAGE/lib/"
+echo "[bundle] installing production dependencies"
+( cd "$STAGE/lib" && npm ci --omit=dev --ignore-scripts >/dev/null 2>&1 )
+rm -f "$STAGE/lib/package-lock.json"
+
+# 4. Vendored Node + launcher (the launcher uses the bundled Node by relative
+#    path, so no system Node is ever needed).
+#
+# `--liftoff-only`: keep tree-sitter's large WASM grammars on V8's Liftoff
+# baseline compiler so they never reach the turboshaft optimizing tier, whose
+# per-compilation Zone arena OOMs the whole process (`Fatal process out of
+# memory: Zone`) on Node >= 22 — even with tens of GB free. The flag is read at
+# V8 engine init so it must be on node's command line; the parse worker inherits
+# it. See issues #293/#298 and src/extraction/wasm-runtime-flags.ts. (The CLI
+# also self-relaunches with this flag when launched without it, so non-bundled
+# runs are covered too; passing it here avoids that extra spawn.)
+if [ "$OSFAM" = "win32" ]; then
+  cp "$NODE_BIN" "$STAGE/node.exe"
+  printf '@"%%~dp0..\\node.exe" --liftoff-only "%%~dp0..\\lib\\dist\\bin\\homegraph.js" %%*\r\n' \
+    > "$STAGE/bin/homegraph.cmd"
+else
+  cp "$NODE_BIN" "$STAGE/node"
+  cat > "$STAGE/bin/homegraph" <<'LAUNCH'
+#!/bin/sh
+# Resolve symlinks (e.g. the ~/.local/bin/homegraph link install.sh creates) so
+# we find the real bundle dir, not the symlink's location.
+SELF="$0"
+while [ -L "$SELF" ]; do
+  target="$(readlink "$SELF")"
+  case "$target" in
+    /*) SELF="$target" ;;
+    *) SELF="$(dirname "$SELF")/$target" ;;
+  esac
+done
+DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
+# --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
+exec "$DIR/node" --liftoff-only "$DIR/lib/dist/bin/homegraph.js" "$@"
+LAUNCH
+  chmod +x "$STAGE/bin/homegraph"
+fi
+
+# 5. Archive (.zip for Windows, .tar.gz otherwise).
+mkdir -p "$OUT"
+if [ "$OSFAM" = "win32" ]; then
+  ARCHIVE="$OUT/homegraph-${TARGET}.zip"
+  rm -f "$ARCHIVE"
+  ( cd "$WORK" && zip -rqX "$ARCHIVE" "homegraph-${TARGET}" )
+else
+  ARCHIVE="$OUT/homegraph-${TARGET}.tar.gz"
+  # --no-xattrs: don't embed macOS xattrs that make GNU tar warn on Linux.
+  tar --no-xattrs -czf "$ARCHIVE" -C "$WORK" "homegraph-${TARGET}"
+fi
+echo "[bundle] wrote ${ARCHIVE} ($(du -h "$ARCHIVE" | cut -f1))"