deepbom 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (C) 2026 Jun-Hwan Kwon. All rights reserved.
+
+This repository and its generated software artifacts are currently provided as
+private research software. No license is granted to copy, modify, distribute,
+sublicense, reverse engineer, or create derivative works from the source code,
+WebAssembly modules, generated JavaScript bindings, or packaged executables,
+except where a separate file or component carries an explicit license.
+
+Access to the hosted service does not grant a software or implementation
+license.
+
+Future public releases may license selected contracts, conformance fixtures,
+validation data, or automation clients separately. A license applies only to
+the files and versions that explicitly carry it. Third-party dependencies and
+model artifacts remain subject to their respective licenses.

package/README.md

@@ -0,0 +1,111 @@
+# deepbom
+
+Deployment-artifact analysis for on-device neural network models.
+
+Answers questions you otherwise have to guess at before shipping a model:
+which operators the XNNPACK delegate will accept, where the graph falls back
+to CPU and how much traffic crosses that boundary, how much of the quantized
+range the weights actually use, and which target profile the numbers apply to.
+
+```console
+$ npx deepbom audit mobilenet_v2_1.0_224_quant.tflite
+
+mobilenet_v2_1.0_224_quant.tflite
+  sha256   f08d447cde49b4e0446428aa921aff0a14ea589fa9c5817b31f83128e9a43c1d
+  format   tflite   size 3.4 MB
+  target   android_mid_a55
+
+graph
+  operators          65
+  tensors            173
+  total MACs         300,775,552
+
+quantization
+  quantized tensors  172 / 173  (99%)
+  per-axis tensors   0
+
+XNNPACK delegate (predicted)
+  delegated ops      64 / 65  (98%)
+  chain breaks       1 effective / 1 total
+  fallback traffic   62.5 KB
+
+findings (7)
+  MEDIUM 1 XNNPACK predicted partition breaks total
+  MEDIUM 17 quantized DEPTHWISE_CONV_2D op(s) use per-tensor weights
+  MEDIUM 53 quantized kernel op(s) use asymmetric UINT8 weights
+  LOW    Input preprocessing contract not encoded in model
+  ...
+```
+
+## Install
+
+Nothing to install:
+
+```console
+npx deepbom audit model.tflite
+```
+
+Or add it to a project:
+
+```console
+npm install --save-dev deepbom
+```
+
+Requires Node.js 20 or newer.
+
+## Usage
+
+```console
+deepbom audit <file> [--target <id>] [--json]
+deepbom targets
+deepbom --version
+```
+
+| Option | |
+| --- | --- |
+| `-t, --target <id>` | Target profile, default `android_mid_a55` |
+| `--json` | Emit the complete analysis ledger as JSON |
+| `-q, --quiet` | Suppress the summary header |
+
+### Target profiles
+
+Cache pressure and roofline results are profile-bound, not global. Run
+`deepbom targets` for the current list; it includes Cortex-A72/A76/A55/A53
+profiles, an illustrative X3/A715 planning profile, x86 AVX2/SSE4 and browser
+WASM SIMD.
+
+```console
+deepbom audit model.tflite --target rpi5_a76
+```
+
+### JSON output
+
+`--json` emits the full ledger: per-operator MACs, cache payload
+decomposition, predicted delegate placement with reasons, per-tensor
+quantization metadata, and the finding queue. Suitable for CI:
+
+```console
+deepbom audit model.tflite --json > audit.json
+```
+
+## Privacy
+
+Analysis runs locally in WebAssembly. The command performs **no network
+access**. Model bytes, filenames and results are never uploaded.
+
+## Scope and limits
+
+This release analyses **TFLite FlatBuffer** artifacts.
+
+Delegate placement is a **static projection** derived from the serialized
+graph. It is not observed runtime behaviour: build configuration, device
+capability and runtime partitioning can differ. Roofline and cache figures are
+target-profile projections, not measurements.
+
+ONNX, GGUF, SafeTensors and Core ML analysis, runtime benchmarks, CycloneDX
+ML-BOM export and the source-pinned execution-provider evidence packs are
+available in the browser version at <https://deepbom.org>.
+
+## License
+
+ISC — see [LICENSE](./LICENSE).

package/bin/deepbom.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// deepbom — deployment-artifact analysis for on-device neural network models.
+//
+// Runs the browser analyzer's WebAssembly module locally. Model bytes never
+// leave the machine; this command performs no network access.
+
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join, basename } from "node:path";
+import { createHash } from "node:crypto";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(HERE, "..");
+const pkg = JSON.parse(await readFile(join(ROOT, "package.json"), "utf8"));
+
+const argv = process.argv.slice(2);
+
+function parseArgs(list) {
+  const opts = { _: [] };
+  for (let i = 0; i < list.length; i += 1) {
+    const a = list[i];
+    if (a === "--json") opts.json = true;
+    else if (a === "--quiet" || a === "-q") opts.quiet = true;
+    else if (a === "--target" || a === "-t") opts.target = list[++i];
+    else if (a === "--help" || a === "-h") opts.help = true;
+    else if (a === "--version" || a === "-v") opts.version = true;
+    else if (a.startsWith("--target=")) opts.target = a.slice(9);
+    else if (a.startsWith("-")) { fail(`unknown option: ${a}`); }
+    else opts._.push(a);
+  }
+  return opts;
+}
+
+function fail(message, code = 2) {
+  process.stderr.write(`deepbom: ${message}\n`);
+  process.exit(code);
+}
+
+const USAGE = `deepbom ${pkg.version} — deployment-artifact analysis for on-device models
+
+USAGE
+  deepbom audit <file> [--target <id>] [--json]
+  deepbom targets
+  deepbom --version
+
+COMMANDS
+  audit     Analyse a model artifact and print a summary
+  targets   List available target profiles
+
+OPTIONS
+  -t, --target <id>   Target profile (default: android_mid_a55)
+      --json          Emit the full analysis ledger as JSON
+  -q, --quiet         Suppress the summary header
+  -h, --help          Show this help
+
+FORMATS
+  TFLite (.tflite) is supported in this release. ONNX, GGUF, SafeTensors and
+  Core ML are available in the browser version at https://deepbom.org
+
+PRIVACY
+  Analysis runs locally. No model bytes, filenames or results are uploaded.
+`;
+
+async function loadEngine() {
+  const mod = await import(new URL("../vendor/tflite_wasm_audit.js", import.meta.url));
+  const wasm = await readFile(new URL("../vendor/tflite_wasm_audit_bg.wasm", import.meta.url));
+  mod.initSync({ module: wasm });
+  return mod;
+}
+
+const fmtInt = (n) => Number(n ?? 0).toLocaleString("en-US");
+function fmtBytes(n) {
+  const v = Number(n ?? 0);
+  if (!Number.isFinite(v) || v <= 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.min(units.length - 1, Math.floor(Math.log(v) / Math.log(1024)));
+  return `${(v / 1024 ** i).toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
+}
+const pct = (n, d) => (d > 0 ? `${((n / d) * 100).toFixed(0)}%` : "n/a");
+
+async function cmdTargets() {
+  const engine = await loadEngine();
+  const profiles = engine.target_profiles() || [];
+  for (const p of profiles) {
+    const id = p?.id ?? p;
+    const label = p?.label ? ` — ${p.label}` : "";
+    process.stdout.write(`${id}${label}\n`);
+  }
+}
+
+async function cmdAudit(opts) {
+  const file = opts._[0];
+  if (!file) fail("audit requires a file path\n\n" + USAGE);
+
+  let bytes;
+  try {
+    bytes = new Uint8Array(await readFile(file));
+  } catch (error) {
+    fail(`cannot read ${file}: ${error.code ?? error.message}`);
+  }
+  if (bytes.length === 0) fail(`${file} is empty`);
+
+  const engine = await loadEngine();
+  const target = opts.target || "android_mid_a55";
+  const known = (engine.target_profiles() || []).map((p) => p?.id ?? p);
+  if (known.length && !known.includes(target)) {
+    fail(`unknown target "${target}". Run: deepbom targets`);
+  }
+
+  let analysis;
+  try {
+    analysis = engine.analyze_tflite_for_target(bytes, basename(file), target);
+  } catch (error) {
+    fail(`analysis failed: ${error?.message ?? error}\n` +
+         `This release supports TFLite FlatBuffer artifacts. ` +
+         `For ONNX, GGUF, SafeTensors and Core ML see https://deepbom.org`, 1);
+  }
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify(analysis, null, 2)}\n`);
+    return;
+  }
+
+  const sha = analysis.model_sha256 || createHash("sha256").update(bytes).digest("hex");
+  const ops = Array.isArray(analysis.ops) ? analysis.ops : [];
+  const delegated = ops.filter((o) => o?.xnnpack_supported === true).length;
+  const findings = Array.isArray(analysis.findings) ? analysis.findings : [];
+  const out = [];
+
+  if (!opts.quiet) {
+    out.push(`${analysis.filename || basename(file)}`);
+    out.push(`  sha256   ${sha}`);
+    out.push(`  format   ${analysis.format ?? "unknown"}   size ${fmtBytes(analysis.file_size ?? bytes.length)}`);
+    out.push(`  target   ${target}`);
+    out.push("");
+  }
+
+  out.push("graph");
+  out.push(`  operators          ${fmtInt(analysis.operator_count)}`);
+  out.push(`  tensors            ${fmtInt(analysis.tensor_count)}`);
+  if (analysis.total_macs != null) out.push(`  total MACs         ${fmtInt(analysis.total_macs)}`);
+  out.push("");
+
+  out.push("quantization");
+  out.push(`  quantized tensors  ${fmtInt(analysis.quantized_tensors)} / ${fmtInt(analysis.tensor_count)}  (${pct(analysis.quantized_tensors, analysis.tensor_count)})`);
+  out.push(`  per-axis tensors   ${fmtInt(analysis.per_channel_tensors)}`);
+  out.push("");
+
+  if (ops.length) {
+    out.push("XNNPACK delegate (predicted)");
+    out.push(`  delegated ops      ${fmtInt(delegated)} / ${fmtInt(ops.length)}  (${pct(delegated, ops.length)})`);
+    if (analysis.xnnpack_effective_chain_breaks != null) {
+      out.push(`  chain breaks       ${fmtInt(analysis.xnnpack_effective_chain_breaks)} effective / ${fmtInt(analysis.xnnpack_chain_breaks)} total`);
+    }
+    if (analysis.fallback_estimated_bytes) {
+      out.push(`  fallback traffic   ${fmtBytes(analysis.fallback_estimated_bytes)}`);
+    }
+    out.push("");
+  }
+
+  if (findings.length) {
+    out.push(`findings (${findings.length})`);
+    for (const f of findings.slice(0, 10)) {
+      const sev = String(f?.severity ?? f?.priority ?? "info").toUpperCase().padEnd(6);
+      const title = f?.title ?? f?.message ?? f?.id ?? "";
+      out.push(`  ${sev} ${title}`);
+    }
+    if (findings.length > 10) out.push(`  ... ${findings.length - 10} more (use --json)`);
+    out.push("");
+  }
+
+  out.push("Predicted delegate placement is a static projection, not observed runtime behaviour.");
+  out.push("Full ledger: deepbom audit <file> --json");
+  process.stdout.write(`${out.join("\n")}\n`);
+}
+
+const opts = parseArgs(argv);
+if (opts.version) { process.stdout.write(`${pkg.version}\n`); process.exit(0); }
+if (opts.help || argv.length === 0) { process.stdout.write(USAGE); process.exit(argv.length === 0 ? 1 : 0); }
+
+const command = opts._.shift();
+try {
+  if (command === "audit") await cmdAudit(opts);
+  else if (command === "targets") await cmdTargets();
+  else fail(`unknown command "${command}"\n\n${USAGE}`);
+} catch (error) {
+  fail(error?.stack ?? String(error), 1);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "deepbom",
+  "version": "0.1.0",
+  "description": "Deployment-artifact analysis for on-device neural network models — local static audit of TFLite graphs, quantization contracts and predicted XNNPACK delegate placement",
+  "type": "module",
+  "bin": {
+    "deepbom": "bin/deepbom.js"
+  },
+  "files": [
+    "bin/",
+    "vendor/",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "ISC",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "tflite",
+    "litert",
+    "onnx",
+    "quantization",
+    "on-device",
+    "edge-ai",
+    "xnnpack",
+    "ml-bom",
+    "cyclonedx",
+    "static-analysis"
+  ],
+  "homepage": "https://deepbom.org",
+  "author": "Jun-Hwan Kwon"
+}