@simulatte/webgpu 0.2.0

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@simulatte/webgpu",
+  "version": "0.2.0",
+  "description": "Doe WebGPU bridge for browserless AI/ML benchmarking and CI",
+  "type": "module",
+  "main": "./src/node-runtime.js",
+  "exports": {
+    ".": {
+      "bun": "./src/bun.js",
+      "default": "./src/node-runtime.js"
+    },
+    "./bun": "./src/bun.js",
+    "./node": "./src/node-runtime.js"
+  },
+  "bin": {
+    "fawn-webgpu-bench": "./bin/fawn-webgpu-bench.js",
+    "fawn-webgpu-compare": "./bin/fawn-webgpu-compare.js"
+  },
+  "files": [
+    "assets/",
+    "bin/",
+    "src/",
+    "scripts/",
+    "native/",
+    "prebuilds/",
+    "binding.gyp",
+    "README.md",
+    "API_CONTRACT.md",
+    "COMPAT_SCOPE.md",
+    "headless-webgpu-comparison.md",
+    "doe-build-metadata.schema.json",
+    "prebuild-metadata.schema.json"
+  ],
+  "scripts": {
+    "install": "node scripts/install.js",
+    "build:addon": "node-gyp rebuild",
+    "build:readme-assets": "node scripts/generate-readme-assets.js",
+    "prebuild": "node scripts/prebuild.js",
+    "test": "node ./test-node.js",
+    "test:bun": "bun ./test-bun.js",
+    "smoke": "node scripts/smoke-test.js"
+  },
+  "keywords": [
+    "webgpu",
+    "doe",
+    "headless",
+    "benchmarking",
+    "ai",
+    "ml",
+    "ci",
+    "bun"
+  ],
+  "author": "Fawn",
+  "license": "ISC"
+}

package/prebuild-metadata.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "WebGPU Package Prebuild Metadata",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "package",
+    "packageVersion",
+    "platform",
+    "arch",
+    "nodeNapiVersion",
+    "doeVersion",
+    "doeBuild",
+    "files",
+    "builtAt"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 1 },
+    "package": { "type": "string" },
+    "packageVersion": { "type": "string" },
+    "platform": { "type": "string" },
+    "arch": { "type": "string" },
+    "nodeNapiVersion": { "type": "integer" },
+    "doeVersion": { "type": "string" },
+    "doeBuild": {
+      "type": "object",
+      "required": [
+        "artifact",
+        "leanVerifiedBuild",
+        "proofArtifactSha256"
+      ],
+      "properties": {
+        "artifact": { "type": "string", "const": "libwebgpu_doe" },
+        "leanVerifiedBuild": { "type": "boolean" },
+        "proofArtifactSha256": {
+          "anyOf": [
+            { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+            { "type": "null" }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "files": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["sha256"],
+        "properties": {
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "builtAt": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/prebuilds/darwin-arm64/metadata.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 1,
+  "package": "@simulatte/webgpu",
+  "packageVersion": "0.2.0",
+  "platform": "darwin",
+  "arch": "arm64",
+  "nodeNapiVersion": 8,
+  "doeVersion": "22613a9b0",
+  "doeBuild": {
+    "artifact": "libwebgpu_doe",
+    "leanVerifiedBuild": false,
+    "proofArtifactSha256": null
+  },
+  "files": {
+    "doe_napi.node": {
+      "sha256": "ccd350506359a770d286f7f3893dd0c6d81582dbcc04524461c9fa81cae4573e"
+    },
+    "libwebgpu_doe.dylib": {
+      "sha256": "30be9ca300c53c0ba02eb76dfa94b683585c20f7a4caaa1f8eeea2cfb17d1f5f"
+    },
+    "libwebgpu_dawn.dylib": {
+      "sha256": "22751faeb459e7a2ec778c0410ca122e23c23366eb3da145c651d1d43e26707d"
+    }
+  },
+  "builtAt": "2026-03-07T03:39:41.504Z"
+}

package/scripts/generate-readme-assets.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+const WORKSPACE_ROOT = resolve(PACKAGE_ROOT, '..', '..');
+const CUBE_SUMMARY_PATH = resolve(WORKSPACE_ROOT, 'bench', 'out', 'cube', 'latest', 'cube.summary.json');
+const OUTPUT_PATH = resolve(PACKAGE_ROOT, 'assets', 'package-surface-cube-snapshot.svg');
+
+const UI_FONT = '"Segoe UI", "Helvetica Neue", Arial, sans-serif';
+const MONO_FONT = 'SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace';
+const TEXT_STROKE = 'paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round;';
+
+const SURFACE_SPECS = [
+  {
+    surface: 'node_package',
+    title: 'Node package lane',
+    supportLabel: 'Primary support',
+    preferredHostProfile: 'mac_apple_silicon',
+    focusSets: ['uploads', 'compute_e2e'],
+    tone: 'left',
+  },
+  {
+    surface: 'bun_package',
+    title: 'Bun package lane',
+    supportLabel: 'Prototype support',
+    preferredHostProfile: 'linux_x64',
+    focusSets: ['compute_e2e', 'uploads'],
+    tone: 'right',
+  },
+];
+
+const STATUS_STYLE = {
+  claimable: { fill: '#16a34a', stroke: '#86efac', label: 'CLAIMABLE' },
+  comparable: { fill: '#d97706', stroke: '#fbbf24', label: 'COMPARABLE' },
+  diagnostic: { fill: '#dc2626', stroke: '#fca5a5', label: 'DIAGNOSTIC' },
+  unimplemented: { fill: '#3f3f46', stroke: '#71717a', label: 'UNIMPLEMENTED' },
+};
+
+function readCubeSummary(summaryPath) {
+  return JSON.parse(readFileSync(summaryPath, 'utf8'));
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+function formatPercent(value) {
+  if (!Number.isFinite(value)) return 'n/a';
+  const sign = value > 0 ? '+' : '';
+  return `${sign}${value.toFixed(1)}%`;
+}
+
+function compactIso(value) {
+  if (!value) return 'n/a';
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return value;
+  return parsed.toISOString().replace('.000Z', 'Z');
+}
+
+function maxGeneratedAt(cells) {
+  const stamps = cells
+    .map((cell) => cell?.latestGeneratedAt ?? '')
+    .filter((stamp) => stamp !== '');
+  if (stamps.length === 0) return 'n/a';
+  return compactIso(stamps.sort().at(-1));
+}
+
+function implementedScore(cell) {
+  if (!cell) return 0;
+  if ((cell.rowCount ?? 0) > 0 || (cell.reportCount ?? 0) > 0) return 2;
+  if (cell.status && cell.status !== 'unimplemented') return 1;
+  return 0;
+}
+
+function selectHostProfile(cells, preferredHostProfile) {
+  const statsByHost = new Map();
+  for (const cell of cells) {
+    const host = cell.hostProfile ?? 'unknown';
+    const current = statsByHost.get(host) ?? {
+      hostProfile: host,
+      populatedCells: 0,
+      implementedCells: 0,
+      totalRows: 0,
+      claimableCells: 0,
+      latestGeneratedAt: '',
+    };
+    const score = implementedScore(cell);
+    if (score === 2) current.populatedCells += 1;
+    if (score >= 1) current.implementedCells += 1;
+    current.totalRows += cell.rowCount ?? 0;
+    if (cell.status === 'claimable') current.claimableCells += 1;
+    if ((cell.latestGeneratedAt ?? '') > current.latestGeneratedAt) {
+      current.latestGeneratedAt = cell.latestGeneratedAt;
+    }
+    statsByHost.set(host, current);
+  }
+
+  const preferred = statsByHost.get(preferredHostProfile);
+  if (preferred && preferred.populatedCells > 0) return preferred.hostProfile;
+
+  const ranked = [...statsByHost.values()].sort((left, right) => {
+    if (right.populatedCells !== left.populatedCells) {
+      return right.populatedCells - left.populatedCells;
+    }
+    if (right.claimableCells !== left.claimableCells) {
+      return right.claimableCells - left.claimableCells;
+    }
+    if (right.totalRows !== left.totalRows) {
+      return right.totalRows - left.totalRows;
+    }
+    if (right.latestGeneratedAt !== left.latestGeneratedAt) {
+      return right.latestGeneratedAt.localeCompare(left.latestGeneratedAt);
+    }
+    return left.hostProfile.localeCompare(right.hostProfile);
+  });
+
+  return ranked[0]?.hostProfile ?? preferredHostProfile;
+}
+
+function findCell(cells, hostProfile, workloadSet) {
+  return cells.find(
+    (cell) => cell.hostProfile === hostProfile && cell.workloadSet === workloadSet,
+  ) ?? {
+    hostProfile,
+    workloadSet,
+    status: 'unimplemented',
+    claimStatus: 'diagnostic',
+    rowCount: 0,
+    latestGeneratedAt: '',
+  };
+}
+
+function focusLabel(workloadSet) {
+  switch (workloadSet) {
+    case 'compute_e2e':
+      return 'Compute E2E';
+    case 'uploads':
+      return 'Uploads';
+    default:
+      return workloadSet;
+  }
+}
+
+function pillForCell(cell) {
+  const claimStatus = cell.claimStatus ?? cell.status ?? 'diagnostic';
+  if (claimStatus === 'claimable') return STATUS_STYLE.claimable;
+  return STATUS_STYLE[cell.status] ?? STATUS_STYLE.diagnostic;
+}
+
+function summarizeFocusCell(cell) {
+  const statusLabel = (pillForCell(cell).label ?? 'DIAGNOSTIC').toLowerCase();
+  return {
+    title: focusLabel(cell.workloadSet),
+    pill: pillForCell(cell),
+    lines: [
+      `${cell.rowCount ?? 0} rows | ${statusLabel}`,
+      Number.isFinite(cell.deltaP50MedianPercent)
+        ? `median p50 delta ${formatPercent(cell.deltaP50MedianPercent)}`
+        : 'median p50 delta n/a',
+    ],
+  };
+}
+
+function renderMetricRow(summary, x, y, toneClass) {
+  return `
+  <rect x="${x}" y="${y}" width="452" height="82" rx="16" class="metric ${toneClass}"/>
+  <text x="${x + 24}" y="${y + 31}" class="metricTitle">${escapeXml(summary.title)}</text>
+  <rect x="${x + 296}" y="${y + 15}" width="132" height="28" rx="14" fill="${summary.pill.fill}" stroke="${summary.pill.stroke}" stroke-width="1.5"/>
+  <text x="${x + 362}" y="${y + 34}" text-anchor="middle" class="pillText">${escapeXml(summary.pill.label)}</text>
+  <text x="${x + 24}" y="${y + 57}" class="metricBody">${escapeXml(summary.lines[0])}</text>
+  <text x="${x + 24}" y="${y + 77}" class="metricBody">${escapeXml(summary.lines[1])}</text>`;
+}
+
+function renderSurfaceCard(spec, cells, x) {
+  const selectedHostProfile = selectHostProfile(cells, spec.preferredHostProfile);
+  const focusCells = spec.focusSets.map((workloadSet) => findCell(cells, selectedHostProfile, workloadSet));
+  const generatedAt = maxGeneratedAt(focusCells);
+  const toneClass = spec.tone === 'left' ? 'toneLeft' : 'toneRight';
+  const focusSummaries = focusCells.map(summarizeFocusCell);
+
+  return `
+  <rect x="${x}" y="176" width="488" height="318" rx="24" class="panel ${toneClass}"/>
+  <text x="${x + 28}" y="216" class="cardTitle">${escapeXml(spec.title)}</text>
+  <text x="${x + 28}" y="244" class="cardMeta">${escapeXml(`${spec.supportLabel} | ${selectedHostProfile}`)}</text>
+  <text x="${x + 28}" y="266" class="cardMeta">${escapeXml(`latest populated cell ${generatedAt}`)}</text>
+${renderMetricRow(focusSummaries[0], x + 18, 300, toneClass)}
+${renderMetricRow(focusSummaries[1], x + 18, 396, toneClass)}`;
+}
+
+function renderSvg(summary) {
+  const cells = summary.cells ?? [];
+  const nodeCells = cells.filter((cell) => cell.surface === 'node_package');
+  const bunCells = cells.filter((cell) => cell.surface === 'bun_package');
+  const nodeHost = selectHostProfile(nodeCells, SURFACE_SPECS[0].preferredHostProfile);
+  const bunHost = selectHostProfile(bunCells, SURFACE_SPECS[1].preferredHostProfile);
+  const generatedAt = maxGeneratedAt([
+    ...SURFACE_SPECS[0].focusSets.map((workloadSet) => findCell(nodeCells, nodeHost, workloadSet)),
+    findCell(nodeCells, nodeHost, 'full_comparable'),
+    ...SURFACE_SPECS[1].focusSets.map((workloadSet) => findCell(bunCells, bunHost, workloadSet)),
+    findCell(bunCells, bunHost, 'full_comparable'),
+  ]);
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
+  <title id="title">Package surface benchmark cube snapshot</title>
+  <desc id="desc">Two-card package surface snapshot for Node and Bun generated from bench/out/cube/latest/cube.summary.json.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#050816"/>
+      <stop offset="100%" stop-color="#0f172a"/>
+    </linearGradient>
+    <linearGradient id="panel-left" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#ef444420"/>
+      <stop offset="60%" stop-color="#ef444426"/>
+      <stop offset="100%" stop-color="#7c3aed22"/>
+    </linearGradient>
+    <linearGradient id="panel-right" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#7c3aed20"/>
+      <stop offset="60%" stop-color="#7c3aed24"/>
+      <stop offset="100%" stop-color="#2563eb22"/>
+    </linearGradient>
+    <style>
+      .title { font: 700 34px ${UI_FONT}; fill: #ffffff; ${TEXT_STROKE} }
+      .subtitle { font: 500 18px ${UI_FONT}; fill: #cbd5e1; ${TEXT_STROKE} }
+      .cardTitle { font: 700 26px ${UI_FONT}; fill: #ffffff; ${TEXT_STROKE} }
+      .cardMeta { font: 500 16px ${UI_FONT}; fill: #cbd5e1; ${TEXT_STROKE} }
+      .metricTitle { font: 700 18px ${UI_FONT}; fill: #ffffff; ${TEXT_STROKE} }
+      .metricBody { font: 500 15px ${MONO_FONT}; fill: #e2e8f0; ${TEXT_STROKE} }
+      .pillText { font: 700 13px ${UI_FONT}; fill: #f8fafc; letter-spacing: 0.5px; ${TEXT_STROKE} }
+      .foot { font: 500 14px ${UI_FONT}; fill: #cbd5e1; ${TEXT_STROKE} }
+      .panel { stroke-width: 4; }
+      .toneLeft { fill: url(#panel-left); stroke: #ef4444; }
+      .toneRight { fill: url(#panel-right); stroke: #2563eb; }
+      .metric { fill: #020617a8; stroke-width: 1.8; }
+      .metric.toneLeft { stroke: #ef4444; }
+      .metric.toneRight { stroke: #2563eb; }
+    </style>
+  </defs>
+  <rect width="1200" height="640" fill="url(#bg)"/>
+  <text x="72" y="72" class="title">@simulatte/webgpu package snapshot</text>
+  <text x="72" y="102" class="subtitle">Derived from bench/out/cube/latest/cube.summary.json | latest populated cell ${escapeXml(generatedAt)}</text>
+  <text x="72" y="128" class="subtitle">Package-surface evidence only. Backend-native strict claim lanes remain separate.</text>
+${renderSurfaceCard(SURFACE_SPECS[0], nodeCells, 72)}
+${renderSurfaceCard(SURFACE_SPECS[1], bunCells, 640)}
+  <text x="72" y="590" class="foot">Generated by nursery/webgpu/scripts/generate-readme-assets.js.</text>
+  <text x="72" y="612" class="foot">Static claim and comparability card from the package-surface cube. It is not a substitute for strict backend reports.</text>
+</svg>
+`;
+}
+
+function main() {
+  const summary = readCubeSummary(CUBE_SUMMARY_PATH);
+  const svg = renderSvg(summary);
+  mkdirSync(dirname(OUTPUT_PATH), { recursive: true });
+  writeFileSync(
+    OUTPUT_PATH,
+    `<!-- Generated by scripts/generate-readme-assets.js. Do not edit by hand. -->\n${svg}`,
+  );
+  console.log(`Wrote ${OUTPUT_PATH}`);
+}
+
+main();

package/scripts/install.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Prebuild-aware install script.
+// Uses prebuilt binaries when available; falls back to node-gyp for contributors.
+
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+
+const platform = process.platform;
+const arch = process.arch;
+const prebuildDir = resolve(PACKAGE_ROOT, 'prebuilds', `${platform}-${arch}`);
+const addonPath = resolve(prebuildDir, 'doe_napi.node');
+
+if (existsSync(addonPath)) {
+  console.log(`@simulatte/webgpu: using prebuilt binary for ${platform}-${arch}`);
+  process.exit(0);
+}
+
+// No prebuild — compile from source.
+console.log(`@simulatte/webgpu: no prebuild for ${platform}-${arch}, compiling from source...`);
+
+try {
+  execFileSync('node-gyp', ['rebuild'], {
+    cwd: PACKAGE_ROOT,
+    stdio: 'inherit',
+  });
+} catch (err) {
+  console.error('@simulatte/webgpu: native addon build failed.');
+  console.error('Ensure you have a C compiler and node-gyp prerequisites installed.');
+  console.error('See https://github.com/nodejs/node-gyp#installation');
+  process.exit(1);
+}

package/scripts/prebuild.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Build and package prebuilt native artifacts for the current platform.
+//
+// Usage:
+//   node scripts/prebuild.js [--zig-out PATH]
+//
+// Produces:
+//   prebuilds/<platform>-<arch>/
+//     doe_napi.node          N-API addon
+//     libwebgpu_doe.<ext>    Doe drop-in WebGPU library
+//     libwebgpu_dawn.<ext>   Dawn sidecar (required by Doe for proc resolution)
+//     metadata.json          Integrity manifest
+//
+// Prerequisites:
+//   1. node-gyp rebuild (or existing build/Release/doe_napi.node)
+//   2. zig build dropin (or existing zig-out/lib artifacts)
+
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { readDoeBuildMetadataFile } from '../src/build_metadata.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+const WORKSPACE_ROOT = resolve(PACKAGE_ROOT, '..', '..');
+
+const { values: args } = parseArgs({
+  options: {
+    'zig-out': { type: 'string', default: '' },
+    'skip-addon-build': { type: 'boolean', default: false },
+  },
+});
+
+const platform = process.platform;
+const arch = process.arch;
+const ext = platform === 'darwin' ? 'dylib' : platform === 'win32' ? 'dll' : 'so';
+
+const zigOutLib = args['zig-out']
+  ? resolve(args['zig-out'], 'lib')
+  : resolve(WORKSPACE_ROOT, 'zig', 'zig-out', 'lib');
+const zigOutShare = args['zig-out']
+  ? resolve(args['zig-out'], 'share')
+  : resolve(WORKSPACE_ROOT, 'zig', 'zig-out', 'share');
+
+const prebuildDir = resolve(PACKAGE_ROOT, 'prebuilds', `${platform}-${arch}`);
+
+function sha256(filePath) {
+  const data = readFileSync(filePath);
+  return createHash('sha256').update(data).digest('hex');
+}
+
+function copyArtifact(src, destName) {
+  if (!existsSync(src)) {
+    console.error(`Missing: ${src}`);
+    return null;
+  }
+  const dest = resolve(prebuildDir, destName);
+  copyFileSync(src, dest);
+  console.log(`  ${destName} <- ${src}`);
+  return { name: destName, sha256: sha256(dest) };
+}
+
+// 1. Build addon if needed.
+const addonSrc = resolve(PACKAGE_ROOT, 'build', 'Release', 'doe_napi.node');
+if (!args['skip-addon-build'] || !existsSync(addonSrc)) {
+  console.log('Building native addon...');
+  execFileSync('node-gyp', ['rebuild'], { cwd: PACKAGE_ROOT, stdio: 'inherit' });
+}
+
+if (!existsSync(addonSrc)) {
+  console.error(`Addon not found at ${addonSrc}. node-gyp rebuild may have failed.`);
+  process.exit(1);
+}
+
+// 2. Locate Doe library.
+const doeLib = resolve(zigOutLib, `libwebgpu_doe.${ext}`);
+if (!existsSync(doeLib)) {
+  console.error(`Doe library not found at ${doeLib}.`);
+  console.error('Run: cd zig && zig build dropin');
+  process.exit(1);
+}
+
+// 3. Locate Dawn sidecar.
+const SIDECAR_CANDIDATES = {
+  darwin: ['libwebgpu_dawn.dylib', 'libwebgpu.dylib'],
+  linux: ['libwebgpu_dawn.so', 'libwebgpu.so'],
+  win32: ['webgpu_dawn.dll', 'webgpu.dll'],
+};
+
+const candidates = SIDECAR_CANDIDATES[platform] || SIDECAR_CANDIDATES.linux;
+let sidecarSrc = null;
+let sidecarName = null;
+for (const name of candidates) {
+  const candidate = resolve(zigOutLib, name);
+  if (existsSync(candidate)) {
+    sidecarSrc = candidate;
+    sidecarName = name;
+    break;
+  }
+}
+
+if (!sidecarSrc) {
+  console.error(`Dawn sidecar not found in ${zigOutLib}. Expected one of: ${candidates.join(', ')}`);
+  console.error('Run: cd zig && zig build dropin (with Dawn sidecar available)');
+  process.exit(1);
+}
+
+const zigBuildMetadataPath = resolve(zigOutShare, 'doe-build-metadata.json');
+const doeBuild = readDoeBuildMetadataFile(zigBuildMetadataPath);
+if (!doeBuild) {
+  console.error(`Doe build metadata not found or invalid at ${zigBuildMetadataPath}.`);
+  console.error('Run: cd zig && zig build dropin [ -Dlean-verified=true ]');
+  process.exit(1);
+}
+
+// 4. Assemble prebuild directory.
+mkdirSync(prebuildDir, { recursive: true });
+console.log(`\nAssembling prebuilds/${platform}-${arch}/`);
+
+const files = {};
+const addonEntry = copyArtifact(addonSrc, 'doe_napi.node');
+if (addonEntry) files[addonEntry.name] = { sha256: addonEntry.sha256 };
+
+const doeEntry = copyArtifact(doeLib, `libwebgpu_doe.${ext}`);
+if (doeEntry) files[doeEntry.name] = { sha256: doeEntry.sha256 };
+
+const sidecarEntry = copyArtifact(sidecarSrc, sidecarName);
+if (sidecarEntry) files[sidecarEntry.name] = { sha256: sidecarEntry.sha256 };
+
+// 5. Write metadata manifest.
+const pkg = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8'));
+let doeVersion = 'unknown';
+try {
+  doeVersion = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
+    cwd: WORKSPACE_ROOT,
+    encoding: 'utf8',
+  }).trim();
+} catch { /* ignore */ }
+
+const metadata = {
+  schemaVersion: 1,
+  package: pkg.name,
+  packageVersion: pkg.version,
+  platform,
+  arch,
+  nodeNapiVersion: 8,
+  doeVersion,
+  doeBuild: {
+    artifact: 'libwebgpu_doe',
+    leanVerifiedBuild: doeBuild.leanVerifiedBuild,
+    proofArtifactSha256: doeBuild.proofArtifactSha256,
+  },
+  files,
+  builtAt: new Date().toISOString(),
+};
+
+const metadataPath = resolve(prebuildDir, 'metadata.json');
+writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n');
+console.log(`  metadata.json`);
+
+// macOS: ad-hoc sign dylibs for distribution.
+if (platform === 'darwin') {
+  console.log('\nSigning dylibs (ad-hoc)...');
+  for (const name of Object.keys(files)) {
+    if (name.endsWith('.dylib')) {
+      try {
+        execFileSync('codesign', ['-s', '-', resolve(prebuildDir, name)], { stdio: 'inherit' });
+      } catch {
+        console.warn(`  Warning: codesign failed for ${name} (may already be signed)`);
+      }
+    }
+  }
+}
+
+console.log(`\nDone. Prebuild artifacts in prebuilds/${platform}-${arch}/`);
+console.log(`Total files: ${Object.keys(files).length}`);