@davidwells/llrt-analyzer 0.1.0

package/src/import-graph.js

@@ -0,0 +1,167 @@
+// @ts-check
+'use strict'
+/**
+ * Import-graph resolver (bead sci-xwk.6).
+ *
+ * Resolve a function handler's transitive runtime imports so the static scan
+ * can see node: builtins, npm packages, and @aws-sdk clients — INCLUDING those
+ * pulled in transitively (a lib like undici/axios can import node:http even when
+ * the service only calls fetch). First-party files are followed fully; npm
+ * packages are scanned to a bounded depth for the node: builtins they use, so a
+ * transitive blocker is attributed with its `via` chain.
+ */
+const fs = require('fs')
+const path = require('path')
+const nodeModule = require('module')
+const precinct = require('precinct')
+
+const debug = safeDebug('llrt:graph')
+
+const IS_BUILTIN =
+  typeof nodeModule.isBuiltin === 'function'
+    ? (n) => nodeModule.isBuiltin(n)
+    : ((set) => (n) => set.has(String(n).replace(/^node:/, '')))(new Set(nodeModule.builtinModules))
+
+/**
+ * @param {string} entryFile absolute path to the handler entry
+ * @param {{ projectDir?: string, maxNpmDepth?: number, maxFiles?: number }} [opts]
+ * @returns {{ builtins: {name:string,file:string,via:string}[], npmPkgs: {name:string,file:string}[], awsSdkClients: string[], firstPartyFiles: string[], scannedFiles: number, errors: string[] }}
+ */
+function resolveImportGraph(entryFile, opts = {}) {
+  const maxNpmDepth = opts.maxNpmDepth == null ? 2 : opts.maxNpmDepth
+  const maxFiles = opts.maxFiles == null ? 4000 : opts.maxFiles
+  const builtins = /** @type {{name:string,file:string,via:string}[]} */ ([])
+  const npmSet = new Map() // pkg -> firstFile
+  const awsSdk = new Set()
+  const errors = []
+  const visited = new Set()
+  const firstParty = new Set()
+  let scanned = 0
+
+  /** @param {string} file @param {number} npmDepth @param {string} via @param {boolean} isFirstParty */
+  function walk(file, npmDepth, via, isFirstParty) {
+    if (!file || visited.has(file) || scanned >= maxFiles) return
+    visited.add(file)
+    if (isFirstParty) firstParty.add(file)
+    let deps
+    try {
+      deps = precinct.paperwork(file, { includeCore: true })
+    } catch (err) {
+      errors.push(`parse ${rel(opts.projectDir, file)}: ${err.message}`)
+      return
+    }
+    scanned += 1
+    for (const dep of deps) {
+      if (IS_BUILTIN(dep)) {
+        builtins.push({ name: normalizeBuiltin(dep), file: rel(opts.projectDir, file), via })
+        continue
+      }
+      if (dep.startsWith('.') || path.isAbsolute(dep)) {
+        // First-party relative import — always follow, stays first-party.
+        const resolved = resolveLocal(dep, file)
+        if (resolved) walk(resolved, npmDepth, via, isFirstParty)
+        else errors.push(`unresolved ${dep} from ${rel(opts.projectDir, file)}`)
+        continue
+      }
+      // Bare specifier = npm package (or scoped). Record it.
+      const pkg = packageName(dep)
+      const isAwsSdk = pkg.startsWith('@aws-sdk/') || pkg.startsWith('@smithy/') || pkg.startsWith('@aws-crypto/')
+      if (isAwsSdk) awsSdk.add(pkg)
+      if (!npmSet.has(pkg)) npmSet.set(pkg, rel(opts.projectDir, file))
+      // Do NOT traverse AWS SDK / smithy internals: LLRT pre-bundles them and
+      // routes them through fetch, so their internal node:http usage is a false
+      // positive and their sub-packages are noise. resolveSdkBundle handles
+      // bundle membership at the client level instead.
+      if (isAwsSdk) continue
+      // Bounded transitive scan for node: builtins the package uses.
+      if (npmDepth < maxNpmDepth) {
+        const entry = resolvePackageEntry(pkg, file)
+        // npm internals are NOT first-party (their own disallowed patterns
+        // shouldn't be attributed to the service source).
+        if (entry) walk(entry, npmDepth + 1, via === '(direct)' ? pkg : via, false)
+      }
+    }
+  }
+
+  walk(entryFile, 0, '(direct)', true)
+
+  return {
+    builtins: dedupeBuiltins(builtins),
+    npmPkgs: [...npmSet.entries()].map(([name, file]) => ({ name, file })),
+    awsSdkClients: [...awsSdk],
+    firstPartyFiles: [...firstParty],
+    scannedFiles: scanned,
+    errors,
+  }
+}
+
+function normalizeBuiltin(n) {
+  return String(n).replace(/^node:/, '')
+}
+function dedupeBuiltins(list) {
+  const seen = new Map()
+  for (const b of list) {
+    const key = `${b.name}|${b.via}`
+    if (!seen.has(key)) seen.set(key, b)
+  }
+  return [...seen.values()]
+}
+function packageName(spec) {
+  if (spec.startsWith('@')) {
+    const [scope, name] = spec.split('/')
+    return name ? `${scope}/${name}` : scope
+  }
+  return spec.split('/')[0]
+}
+const SOURCE_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx']
+function resolveLocal(dep, fromFile) {
+  const base = path.resolve(path.dirname(fromFile), dep)
+  const candidates = [base]
+  // TypeScript ESM writes imports with a .js/.mjs/.cjs extension even though the
+  // source is .ts/.mts/.cts — remap the extension so we resolve the real file.
+  const ext = path.extname(base)
+  if (['.js', '.mjs', '.cjs'].includes(ext)) {
+    const noExt = base.slice(0, -ext.length)
+    for (const e of SOURCE_EXTS) candidates.push(noExt + e)
+  } else {
+    for (const e of SOURCE_EXTS) candidates.push(base + e)
+  }
+  // index files (directory imports)
+  for (const e of SOURCE_EXTS) candidates.push(path.join(base, `index${e}`))
+  for (const c of candidates) {
+    try {
+      if (fs.statSync(c).isFile()) return c
+    } catch (_) {
+      /* ignore */
+    }
+  }
+  return null
+}
+function resolvePackageEntry(pkg, fromFile) {
+  try {
+    // Resolve the package.json to find its main/module without executing it.
+    const pkgJsonPath = require.resolve(`${pkg}/package.json`, { paths: [path.dirname(fromFile)] })
+    // eslint-disable-next-line import/no-dynamic-require, global-require
+    const meta = require(pkgJsonPath)
+    const rel2 = meta.module || meta.main || 'index.js'
+    const entry = path.join(path.dirname(pkgJsonPath), rel2)
+    if (fs.existsSync(entry) && fs.statSync(entry).isFile()) return entry
+    const idx = path.join(path.dirname(pkgJsonPath), 'index.js')
+    return fs.existsSync(idx) ? idx : null
+  } catch (_) {
+    return null
+  }
+}
+function rel(projectDir, file) {
+  return projectDir ? path.relative(projectDir, file) : file
+}
+function safeDebug(ns) {
+  try {
+    // eslint-disable-next-line global-require
+    return require('@davidwells/smart-log/debug')(ns)
+  } catch (_) {
+    return () => {}
+  }
+}
+
+module.exports = { resolveImportGraph }

package/src/index.js

@@ -0,0 +1,86 @@
+// @ts-check
+'use strict'
+/**
+ * llrt-analyzer — public API (bead sci-xwk.2).
+ *
+ * Decide, per Lambda function, whether it can run on AWS LLRT (QuickJS) for
+ * ~10x faster cold starts, and help flip it. Tier 1 (static) works with no LLRT
+ * binary; Tiers 2/3 (local call-comparison, opt-in deploy-verify) are layered on
+ * in later beads. See docs/plans/llrt-analyzer.md.
+ */
+const kb = require('./knowledge-base')
+const { staticScan } = require('./static-scan')
+const { resolveImportGraph } = require('./import-graph')
+const { emptyVerdict, finalizeRecommendation } = require('./verdict')
+const { discoverFromServerless, writeResultJson } = require('./service')
+
+/**
+ * Tier-2 hook. sci-xwk.19 (localCallCompare) registers a runner here so the
+ * static tier stays usable with no LLRT binary. Signature:
+ * (verdict, input) => Promise<FunctionVerdict>.
+ * @type {null | ((v: import('./verdict').FunctionVerdict, input: any) => Promise<import('./verdict').FunctionVerdict>)}
+ */
+let localCallCompareHook = null
+/** @param {typeof localCallCompareHook} fn */
+function registerLocalCallCompare(fn) {
+  localCallCompareHook = fn
+}
+
+/**
+ * Analyze one function entrypoint through the requested tiers.
+ * v0.1: static tier only. localCallCompare()/deployVerify() land in sci-xwk.19+.
+ * @param {{ entryPoint: string, projectDir?: string, fn?: string, llrtVersion?: string, tiers?: string[], corpus?: any[], handlerExport?: string, cache?: boolean, cacheFile?: string, targetArch?: string }} input
+ * @returns {Promise<import('./verdict').FunctionVerdict>}
+ */
+async function analyzeFunction(input) {
+  const tiers = input.tiers || ['static']
+  let verdict = staticScan(input)
+  if (tiers.includes('local') && localCallCompareHook) {
+    verdict = await localCallCompareHook(verdict, input)
+  }
+  return finalizeRecommendation(verdict)
+}
+
+/**
+ * Analyze every function in a service — discovered from serverless.yml or passed
+ * explicitly (bead sci-xwk.28). Writes result.json when `resultFile` is given.
+ * @param {{ projectDir: string, functions?: {fn:string, entryPoint:string, handlerExport?:string}[], tiers?: string[], llrtVersion?: string, resultFile?: string, cache?: boolean, cacheFile?: string, targetArch?: string }} input
+ * @returns {Promise<import('./verdict').FunctionVerdict[]>}
+ */
+async function analyzeService(input) {
+  const fns = input.functions && input.functions.length ? input.functions : discoverFromServerless(input.projectDir)
+  const out = []
+  for (const f of fns) {
+    // eslint-disable-next-line no-await-in-loop
+    out.push(
+      await analyzeFunction({
+        ...f,
+        projectDir: input.projectDir,
+        tiers: input.tiers,
+        llrtVersion: input.llrtVersion,
+        cache: input.cache,
+        cacheFile: input.cacheFile,
+        targetArch: input.targetArch,
+      }),
+    )
+  }
+  if (input.resultFile) writeResultJson(out, input.resultFile)
+  return out
+}
+
+// Register the Tier-2 runner so `tiers:['static','local']` works out of the box.
+// eslint-disable-next-line global-require
+registerLocalCallCompare(require('./local-compare').localCallCompare)
+
+module.exports = {
+  analyzeFunction,
+  analyzeService,
+  registerLocalCallCompare,
+  staticScan,
+  resolveImportGraph,
+  discoverFromServerless,
+  writeResultJson,
+  emptyVerdict,
+  finalizeRecommendation,
+  ...kb,
+}

package/src/knowledge-base.js

@@ -0,0 +1,139 @@
+// @ts-check
+'use strict'
+/**
+ * Tier-0 knowledge base (bead sci-xwk.3).
+ *
+ * Versioned, org-pinned compat data: node-builtin support matrix, AWS-SDK
+ * bundle membership, and known-bad npm packages. Everything downstream cross-
+ * references this. Pinning ONE org-wide LLRT version keeps verdicts
+ * reproducible; `scripts/refresh.js` (sci-xwk.4) regenerates the data files.
+ */
+const path = require('path')
+
+/** The single org-wide pinned LLRT version. Bump deliberately (re-verifies all). */
+const ORG_PINNED_LLRT_VERSION = '0.8.1-beta'
+
+const DATA_DIR = path.join(__dirname, '..', 'data')
+
+/** @typedef {'supported'|'partial'|'planned'|'unsupported'|'unknown'} BuiltinStatus */
+
+/** @param {string} [version] */
+function loadCompatTable(version = ORG_PINNED_LLRT_VERSION) {
+  return requireData(`compat-table.${version}.json`, version)
+}
+/** @param {string} [version] */
+function loadSdkBundle(version = ORG_PINNED_LLRT_VERSION) {
+  return requireData(`sdk-bundle.${version}.json`, version)
+}
+function loadKnownBad() {
+  // eslint-disable-next-line global-require
+  return require(path.join(DATA_DIR, 'known-bad.json'))
+}
+
+/**
+ * Confirmed behavioral quirks (source-signature → root cause + fix) that the
+ * static tier and deploy guard consult so behavioral breaks (e.g. hono/cors
+ * emptying the body under LLRT) are caught without a local run. Optional file —
+ * absence is not an error (returns an empty set).
+ * @param {string} [version]
+ * @returns {{ quirks: {id:string, signature:string, files?:string, severity:'blocker'|'warning', api:string, note:string, fix:string, tracking?:string}[] }}
+ */
+function loadKnownQuirks(version = ORG_PINNED_LLRT_VERSION) {
+  try {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    return require(path.join(DATA_DIR, `known-quirks.${version}.json`))
+  } catch (_) {
+    return { quirks: [] }
+  }
+}
+
+/**
+ * Pinned sha256 checksums of the extracted llrt binary per release asset, used
+ * to verify downloads. Optional — absence means "verify nothing, warn".
+ * @param {string} [version]
+ * @returns {{ algorithm?: string, binaries: Record<string,string> }}
+ */
+function loadBinaryChecksums(version = ORG_PINNED_LLRT_VERSION) {
+  try {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    return require(path.join(DATA_DIR, `llrt-binary-checksums.${version}.json`))
+  } catch (_) {
+    return { binaries: {} }
+  }
+}
+
+function requireData(file, version) {
+  try {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    return require(path.join(DATA_DIR, file))
+  } catch (err) {
+    throw new Error(
+      `llrt-analyzer: no knowledge-base data for LLRT version "${version}" (${file}). ` +
+        `Run scripts/refresh.js to generate it, or use the pinned version ${ORG_PINNED_LLRT_VERSION}.`,
+    )
+  }
+}
+
+/**
+ * Status of a node: builtin under LLRT. Accepts 'node:crypto' or 'crypto'.
+ * @param {string} name
+ * @param {string} [version]
+ * @returns {BuiltinStatus}
+ */
+function builtinStatus(name, version = ORG_PINNED_LLRT_VERSION) {
+  const table = loadCompatTable(version)
+  const key = String(name).replace(/^node:/, '')
+  const status = table.builtins[key]
+  return /** @type {BuiltinStatus} */ (status || 'unknown')
+}
+
+/** @param {string} name @param {string} [version] */
+function builtinNote(name, version = ORG_PINNED_LLRT_VERSION) {
+  const table = loadCompatTable(version)
+  const key = String(name).replace(/^node:/, '')
+  return (table.notes && table.notes[key]) || ''
+}
+
+/**
+ * Resolve which LLRT SDK bundle a set of @aws-sdk packages needs, and which
+ * clients must be bundled INTO the artifact (absent from the chosen bundle).
+ * (bead sci-xwk.9 uses this.)
+ * @param {string[]} clients  e.g. ['@aws-sdk/client-dynamodb','@aws-sdk/lib-dynamodb']
+ * @param {string} [version]
+ * @returns {{ bundle: 'no-sdk'|'std-sdk'|'full-sdk', bundleIn: string[] }}
+ */
+function resolveSdkBundle(clients, version = ORG_PINNED_LLRT_VERSION) {
+  const map = loadSdkBundle(version)
+  const uniq = [...new Set((clients || []).filter(Boolean))]
+  if (uniq.length === 0) return { bundle: 'no-sdk', bundleIn: [] }
+
+  const inAlways = (c) => map.always.some((a) => c === a || c.startsWith(a))
+  const inStd = (c) => map.std.includes(c)
+  const inFull = (c) => map.full.includes(c)
+
+  let needFull = false
+  const bundleIn = []
+  for (const c of uniq) {
+    if (inAlways(c) || inStd(c)) continue
+    if (inFull(c)) {
+      needFull = true
+      continue
+    }
+    // Not in any known bundle -> must be bundled into the artifact.
+    bundleIn.push(c)
+  }
+  const bundle = needFull ? 'full-sdk' : 'std-sdk'
+  return { bundle, bundleIn }
+}
+
+module.exports = {
+  ORG_PINNED_LLRT_VERSION,
+  loadCompatTable,
+  loadSdkBundle,
+  loadKnownBad,
+  loadKnownQuirks,
+  loadBinaryChecksums,
+  builtinStatus,
+  builtinNote,
+  resolveSdkBundle,
+}

package/src/local-compare.js

@@ -0,0 +1,156 @@
+// @ts-check
+'use strict'
+/**
+ * Tier-2 local call-comparison (beads sci-xwk.19 + .22). Bundle the handler for
+ * LLRT, then for each corpus event run it under BOTH Node and the LLRT binary
+ * with downstream calls intercepted (fetch + AWS SDK recorder), and diff the
+ * behavior. This is the decisive tier: empirical, no deploy, no side effects.
+ *
+ * Also stamps provenance + confidence (host arch vs Lambda's linux target),
+ * measures the cold-start win, and caches the (expensive) result keyed on the
+ * built-bundle content so repeat runs are instant on unchanged inputs.
+ */
+const path = require('path')
+const { buildForLlrt } = require('./build-for-llrt')
+const { getLlrtBinary, isCached, hostTarget } = require('./binary-manager')
+const { runUnder } = require('./run-under')
+const { diffRun } = require('./diff')
+const { attributeError } = require('./error-map')
+const { loadCorpus, synthApiGwV2 } = require('./corpus')
+const { measureColdStart } = require('./cold-start')
+const { finalizeRecommendation } = require('./verdict')
+const persist = require('./persist')
+
+/**
+ * localCallCompare hook — enriches a static verdict with Tier-2 evidence.
+ * @param {import('./verdict').FunctionVerdict} verdict
+ * @param {{ entryPoint: string, projectDir?: string, corpus?: any[], handlerExport?: string, llrtVersion?: string, targetArch?: string, cache?: boolean, cacheFile?: string, measureColdStart?: boolean }} input
+ * @returns {Promise<import('./verdict').FunctionVerdict>}
+ */
+async function localCallCompare(verdict, input) {
+  const sdk = verdict.sdkBundle === 'full-sdk' ? 'full-sdk' : verdict.sdkBundle === 'no-sdk' ? 'no-sdk' : 'std-sdk'
+  const version = input.llrtVersion || verdict.llrtVersion
+
+  // Provenance: we run on the HOST arch/OS, but Lambda runs linux. Record the
+  // (mis)match so confidence reflects it — a darwin "compatible" is not a linux
+  // guarantee (this whole tool exists because host≠target can bite).
+  const host = hostTarget()
+  const target = { platform: 'linux', arch: input.targetArch || 'arm64' }
+  const hostMatchesTarget = host.platform === target.platform && host.arch === target.arch
+  verdict.provenance = {
+    tier: 'local',
+    hostPlatform: host.platform,
+    hostArch: host.arch,
+    targetPlatform: target.platform,
+    targetArch: target.arch,
+    hostMatchesTarget,
+  }
+  if (!hostMatchesTarget) {
+    verdict.warnings.push({
+      kind: 'partial-api',
+      note: `verified on ${host.platform}/${host.arch}, but Lambda runs ${target.platform}/${target.arch} — behavior could differ; confidence lowered to medium`,
+      fix: 'for full rigor run the linux LLRT binary in a container, or use the opt-in deploy-verify tier.',
+    })
+  }
+
+  // 1. Bundle for LLRT (aws-sdk aliased to the recorder — no side effects).
+  let build
+  try {
+    build = await buildForLlrt({ entryPoint: input.entryPoint, handlerExport: input.handlerExport })
+  } catch (err) {
+    verdict.warnings.push({ kind: 'partial-api', note: `could not bundle for LLRT: ${err.message}`, fix: 'ensure esbuild can bundle the handler (TS transpile, resolvable imports).' })
+    return verdict
+  }
+  if (build.errors.length) {
+    verdict.blockers.push({ api: 'bundle', fatal: true, fix: `esbuild failed: ${build.errors[0]}` })
+    return verdict
+  }
+
+  // 2. Cache: content-based key on the built bundle. A hit replays the expensive
+  // verdict (the node+llrt runs) verbatim — only the bundle changing invalidates.
+  const cacheEnabled = input.cache !== false
+  const storeFile = input.cacheFile || persist.DEFAULT_STORE
+  const lockfile = persist.findLockfile(input.projectDir || path.dirname(input.entryPoint))
+  const key = persist.bundleKey({ bundleFile: build.outFile, lockfile, llrtVersion: version, fn: verdict.fn })
+  if (cacheEnabled) {
+    const hit = persist.getCached(storeFile, key)
+    if (hit) {
+      hit.fn = verdict.fn
+      hit.provenance = { tier: 'local', ...(hit.provenance || {}), cached: true }
+      return hit
+    }
+  }
+
+  // 3. LLRT binary (skip Tier 2 gracefully when offline + not cached).
+  let bin
+  try {
+    if (!isCached({ version, sdk })) {
+      // getLlrtBinary will download; allow it, but surface a clean skip on failure.
+    }
+    bin = await getLlrtBinary({ version, sdk })
+  } catch (err) {
+    verdict.warnings.push({ kind: 'partial-api', note: `Tier 2 skipped — LLRT binary unavailable: ${err.message}`, fix: 'run online once to cache the LLRT binary, then re-run for a definitive verdict.' })
+    return verdict
+  }
+
+  // 4. Corpus: fixtures-first (sci-xwk.23), else synthetic per adapter.
+  const corpus = loadCorpus({ projectDir: input.projectDir || '.', fnName: verdict.fn, explicit: input.corpus })
+
+  verdict.ranLocal = true
+  verdict.provenance.corpusSize = corpus.length
+  const attributed = new Set()
+  for (let i = 0; i < corpus.length; i += 1) {
+    const event = corpus[i]
+    const label = event && event.routeKey ? event.routeKey : `event#${i}`
+    // eslint-disable-next-line no-await-in-loop
+    const nodeRun = runUnder({ runtime: 'node', bundleFile: build.outFile, event, resultMarker: build.resultMarker })
+    // eslint-disable-next-line no-await-in-loop
+    const llrtRun = runUnder({ runtime: 'llrt', bin, bundleFile: build.outFile, event, resultMarker: build.resultMarker })
+
+    if (!llrtRun.ok) {
+      const at = attributeError(`${llrtRun.error || ''} ${llrtRun.stack || ''} ${llrtRun.stderr || ''}`)
+      const api = at ? at.api : 'llrt-runtime'
+      if (!attributed.has(api) && !verdict.blockers.some((b) => b.api === api)) {
+        attributed.add(api)
+        const detail = (llrtRun.stderr || llrtRun.error || '').trim().slice(0, 300)
+        verdict.blockers.push({ api, fatal: true, fix: at ? at.fix : `LLRT run failed for ${label}: ${detail}` })
+      }
+    }
+    for (const d of diffRun(label, nodeRun, llrtRun)) verdict.diffs.push(d)
+  }
+
+  // 5. Cold-start win — the number that justifies the switch (idea #3).
+  if (input.measureColdStart !== false && !verdict.blockers.some((b) => b.fatal)) {
+    try {
+      verdict.coldStartDeltaMs = measureColdStart({ llrtBin: bin, bundleFile: build.outFile })
+    } catch (_) {
+      /* non-fatal — leave unmeasured */
+    }
+  }
+
+  // 6. Promote confirmed partial APIs to verified when the runs are clean.
+  if (!verdict.blockers.some((b) => b.fatal) && verdict.diffs.length === 0) {
+    const promoted = []
+    verdict.warnings = verdict.warnings.filter((w) => {
+      if (w.kind === 'partial-api' && /node:/.test(w.note)) {
+        const m = w.note.match(/node:([a-z0-9_/]+)/i)
+        if (m) promoted.push(`node:${m[1]} (used calls behaved identically)`)
+        return false
+      }
+      return true
+    })
+    verdict.verified.push(...promoted)
+  }
+
+  // 7. Persist the finalized verdict so the next run (same bundle) is instant.
+  if (cacheEnabled) {
+    try {
+      persist.saveVerdict(storeFile, key, finalizeRecommendation(verdict))
+    } catch (_) {
+      /* cache is best-effort */
+    }
+  }
+  return verdict
+}
+
+module.exports = { localCallCompare, synthApiGwV2 }

package/src/persist.js

@@ -0,0 +1,110 @@
+// @ts-check
+'use strict'
+/**
+ * "llrtable" verdict persistence + cache invalidation (bead sci-xwk.35).
+ *
+ * The expensive local/deploy tiers are cached so we don't re-verify every CI
+ * run. The verdict is keyed on hash(bundle-inputs + lockfile + llrtVersion): a
+ * dependency/bundle/LLRT-version change invalidates it. NOTE: the cheap Tier-1
+ * disallowed-API scan is expected to run on EVERY CI run regardless of this
+ * cache (a code-only change can introduce an unsupported API) — see static-scan.
+ *
+ * In smart-ci this maps onto manifest-core storage/hashing; here we provide a
+ * portable JSON-file store so the analyzer is usable standalone.
+ */
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const crypto = require('crypto')
+
+/** Default cache store (shared with the binary cache root). */
+const DEFAULT_STORE = path.join(os.homedir(), '.smart-ci', 'llrt', 'verdict-cache.json')
+
+/**
+ * Compute the cache key for a function's llrtable verdict.
+ * @param {{ files: string[], lockfile?: string, llrtVersion: string }} input
+ */
+function llrtableKey(input) {
+  const h = crypto.createHash('sha256')
+  h.update(`llrt:${input.llrtVersion}\n`)
+  for (const f of [...input.files].sort()) {
+    try {
+      h.update(`${f}:${fs.statSync(f).mtimeMs}:${fs.statSync(f).size}\n`)
+    } catch (_) {
+      h.update(`${f}:missing\n`)
+    }
+  }
+  if (input.lockfile && fs.existsSync(input.lockfile)) {
+    h.update(fs.readFileSync(input.lockfile))
+  }
+  return h.digest('hex').slice(0, 24)
+}
+
+/**
+ * Content-based cache key for the EXPENSIVE tier. Hashes the built verify bundle
+ * (which already reflects every transitive source + transpile), plus the
+ * lockfile and LLRT version. Content-based ⇒ the same inputs hit the cache
+ * across machines/CI runners, not just where it was first computed (idea #29).
+ * @param {{ bundleFile: string, lockfile?: string, llrtVersion: string, fn?: string }} input
+ */
+function bundleKey(input) {
+  const h = crypto.createHash('sha256')
+  h.update(`llrt:${input.llrtVersion}\nfn:${input.fn || ''}\n`)
+  try {
+    // Normalize the ONE volatile token esbuild injects — the random verify
+    // temp-dir name (llrt-verify-XXXXXX) appears in a path comment and would
+    // otherwise make every build hash differently, defeating the cache.
+    const code = fs.readFileSync(input.bundleFile, 'utf8').replace(/llrt-verify-[A-Za-z0-9]+/g, 'llrt-verify-X')
+    h.update(code)
+  } catch (_) {
+    h.update('no-bundle\n')
+  }
+  if (input.lockfile && fs.existsSync(input.lockfile)) h.update(fs.readFileSync(input.lockfile))
+  return h.digest('hex').slice(0, 24)
+}
+
+/** Find the nearest lockfile above a dir (npm/pnpm/yarn), or '' if none. */
+function findLockfile(startDir) {
+  let dir = startDir
+  for (let i = 0; i < 8 && dir; i += 1) {
+    for (const name of ['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock', 'bun.lockb']) {
+      const p = path.join(dir, name)
+      if (fs.existsSync(p)) return p
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return ''
+}
+
+/** @param {string} storeFile */
+function loadStore(storeFile) {
+  try {
+    return JSON.parse(fs.readFileSync(storeFile, 'utf8'))
+  } catch (_) {
+    return {}
+  }
+}
+
+/**
+ * Store the FULL verdict under a key so a cache hit can replay it verbatim.
+ * @param {string} storeFile @param {string} key @param {import('./verdict').FunctionVerdict} verdict
+ */
+function saveVerdict(storeFile, key, verdict) {
+  const store = loadStore(storeFile)
+  store[key] = { savedForVersion: verdict.llrtVersion, verdict }
+  fs.mkdirSync(path.dirname(storeFile), { recursive: true })
+  fs.writeFileSync(storeFile, `${JSON.stringify(store, null, 2)}\n`)
+  return store[key]
+}
+
+/**
+ * @returns {null | import('./verdict').FunctionVerdict} the cached verdict, or null
+ */
+function getCached(storeFile, key) {
+  const entry = loadStore(storeFile)[key]
+  return entry && entry.verdict ? entry.verdict : null
+}
+
+module.exports = { llrtableKey, bundleKey, findLockfile, saveVerdict, getCached, loadStore, DEFAULT_STORE }