@davidwells/llrt-analyzer 0.1.0

package/src/run-under.js

@@ -0,0 +1,52 @@
+// @ts-check
+'use strict'
+/**
+ * Handler invocation shim (bead sci-xwk.17). Run the verify bundle under a
+ * runtime (Node or the LLRT binary) with a corpus event, capture the JSON
+ * result the generated entry prints (recorded calls + response, or the error).
+ */
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync } = require('child_process')
+
+/**
+ * @param {{ runtime: 'node'|'llrt', bin?: string, bundleFile: string, event?: any, resultMarker: string, timeoutMs?: number }} input
+ * @returns {{ ok: boolean, response?: any, calls: any[], error?: string, stack?: string, exit: number|null, stderr?: string, raw?: string }}
+ */
+function runUnder(input) {
+  const cmd = input.runtime === 'llrt' ? input.bin : process.execPath
+  if (!cmd) throw new Error('runUnder: missing binary for runtime ' + input.runtime)
+
+  let eventFile
+  if (input.event !== undefined) {
+    eventFile = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'llrt-evt-')), 'event.json')
+    fs.writeFileSync(eventFile, JSON.stringify(input.event))
+  }
+  const res = spawnSync(cmd, [input.bundleFile], {
+    encoding: 'utf8',
+    timeout: input.timeoutMs || 20000,
+    env: { ...process.env, VERIFY_EVENT_FILE: eventFile || '' },
+    maxBuffer: 16 * 1024 * 1024,
+  })
+  const out = res.stdout || ''
+  const line = out.split('\n').find((l) => l.startsWith(input.resultMarker))
+  if (!line) {
+    return {
+      ok: false,
+      calls: [],
+      error: `no result from ${input.runtime} (exit=${res.status}${res.signal ? `, signal=${res.signal}` : ''})`,
+      stderr: (res.stderr || '').slice(0, 2000),
+      raw: out.slice(0, 500),
+      exit: res.status,
+    }
+  }
+  try {
+    const parsed = JSON.parse(line.slice(input.resultMarker.length))
+    return { calls: [], ...parsed, exit: res.status, stderr: res.stderr }
+  } catch (err) {
+    return { ok: false, calls: [], error: `bad result JSON from ${input.runtime}: ${err.message}`, exit: res.status }
+  }
+}
+
+module.exports = { runUnder }

package/src/runtime/aws-recorder.cjs

@@ -0,0 +1,99 @@
+'use strict'
+/**
+ * AWS SDK recorder shim (bead sci-xwk.16). The verify bundle aliases every
+ * @aws-sdk/* and @smithy/* import to THIS module so that, under BOTH Node and
+ * LLRT, SDK calls are captured SEMANTICALLY (client + command + input) and
+ * return a canned result — no real network, no side effects, uniform capture.
+ *
+ * A Proxy satisfies arbitrary named imports (`{ DynamoDBClient, GetItemCommand }`)
+ * without us enumerating every client/command. Client instances record each
+ * `.send(command)` to globalThis.__LLRT_CALLS__.
+ */
+function record(entry) {
+  const g = globalThis
+  if (!g.__LLRT_CALLS__) g.__LLRT_CALLS__ = []
+  g.__LLRT_CALLS__.push(entry)
+}
+
+function makeExport(name) {
+  // Heuristic: names ending in "Client" are clients; "Command" are commands;
+  // everything else (helpers, enums) becomes a permissive no-op function/object.
+  if (/Client$/.test(name)) {
+    const RecordingClient = class RecordingClient {
+      constructor(config) {
+        this.__service = name.replace(/Client$/, '')
+        this.config = config || {}
+      }
+
+      async send(command) {
+        const commandName = (command && command.constructor && command.constructor.__cmdName) || (command && command.__cmdName) || 'UnknownCommand'
+        record({ kind: 'aws', service: this.__service, command: commandName, input: (command && command.input) || {} })
+        return {} // canned empty result
+      }
+
+      destroy() {}
+    }
+    // Some clients expose static FACTORY methods, most notably lib-dynamodb's
+    // `DynamoDBDocumentClient.from(baseClient, opts)`. We can't enumerate them,
+    // so trap unknown static access and return a factory that yields a
+    // recording client instance — preserving `.send()` capture downstream.
+    return new Proxy(RecordingClient, {
+      get(target, prop, receiver) {
+        if (prop in target || typeof prop === 'symbol') return Reflect.get(target, prop, receiver)
+        return (...args) => new RecordingClient(args[0])
+      },
+    })
+  }
+  if (/Command$/.test(name)) {
+    const Cmd = class RecordingCommand {
+      constructor(input) {
+        this.input = input || {}
+      }
+    }
+    Cmd.__cmdName = name
+    // Also stamp instances so send() can read the command name.
+    Object.defineProperty(Cmd.prototype, 'constructor', { value: Cmd })
+    Cmd.prototype.constructor.__cmdName = name
+    return Cmd
+  }
+  // Generic permissive value: callable + indexable.
+  const fn = function passthrough() {
+    return {}
+  }
+  return new Proxy(fn, { get: () => makeExport('Helper'), apply: () => ({}) })
+}
+
+const cache = new Map()
+function lookup(prop) {
+  if (typeof prop !== 'string') return undefined
+  if (prop === '__esModule') return true
+  if (!cache.has(prop)) cache.set(prop, makeExport(prop))
+  return cache.get(prop)
+}
+
+// The consuming bundle is ESM (esbuild), so `import { SSMClient } from '@aws-sdk/...'`
+// compiles to `ns.SSMClient` where `ns = __toESM(require(<this>))`. esbuild's
+// __toESM builds `Object.create(getPrototypeOf(mod))` then copies mod's OWN
+// enumerable props — a bare `get`-only Proxy exposes ZERO own props, so every
+// named import would resolve to undefined ("not a function" at `new X()"). To
+// survive that interop we put the name-resolving trap on the PROTOTYPE: __toESM
+// preserves the prototype, so `ns.SSMClient` walks the chain into this trap.
+// (Works identically under Node and LLRT/QuickJS.)
+const nsProto = new Proxy(
+  {},
+  {
+    get(_t, prop) {
+      return lookup(prop)
+    },
+  },
+)
+
+module.exports = new Proxy(
+  Object.create(nsProto),
+  {
+    get(_target, prop) {
+      if (prop === 'default') return module.exports
+      return lookup(prop)
+    },
+  },
+)

package/src/service.js

@@ -0,0 +1,77 @@
+// @ts-check
+'use strict'
+/**
+ * Service discovery + result emission (beads sci-xwk.28 + .26).
+ * Parse a Serverless-Framework service's functions -> entrypoints, and write the
+ * machine-readable verdict (result.json.llrtCandidates[]) for CI to jq.
+ */
+const fs = require('fs')
+const path = require('path')
+
+const SOURCE_EXTS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs']
+
+/**
+ * Discover Lambda functions + their handler entrypoints from serverless.yml.
+ * @param {string} serviceDir
+ * @returns {{ fn: string, entryPoint: string, handlerExport: string }[]}
+ */
+function discoverFromServerless(serviceDir) {
+  const ymlPath = ['serverless.yml', 'serverless.yaml'].map((f) => path.join(serviceDir, f)).find((p) => fs.existsSync(p))
+  if (!ymlPath) return []
+  // eslint-disable-next-line global-require
+  const YAML = require('yaml')
+  let doc
+  try {
+    // Strip CloudFormation short tags (!Ref/!Sub/!GetAtt/...) so the parser
+    // doesn't warn; we only read functions.*.handler.
+    const raw = fs.readFileSync(ymlPath, 'utf8').replace(/!(?:Ref|Sub|GetAtt|Equals|Join|Select|Split|FindInMap|If|Not|And|Or|Base64|Cidr|ImportValue|Condition|Transform|GetAZs)\b/g, '')
+    doc = YAML.parse(raw)
+  } catch (_) {
+    return []
+  }
+  const functions = (doc && doc.functions) || {}
+  const out = []
+  for (const [fn, def] of Object.entries(functions)) {
+    const handler = def && /** @type {any} */ (def).handler
+    if (!handler || typeof handler !== 'string') continue
+    const dot = handler.lastIndexOf('.')
+    const fileRel = handler.slice(0, dot)
+    const handlerExport = handler.slice(dot + 1)
+    const entryPoint = resolveEntry(path.join(serviceDir, fileRel))
+    if (entryPoint) out.push({ fn, entryPoint, handlerExport })
+  }
+  return out
+}
+
+function resolveEntry(base) {
+  for (const e of SOURCE_EXTS) {
+    if (fs.existsSync(base + e)) return base + e
+  }
+  for (const e of SOURCE_EXTS) {
+    const idx = path.join(base, `index${e}`)
+    if (fs.existsSync(idx)) return idx
+  }
+  return null
+}
+
+/**
+ * @param {import('./verdict').FunctionVerdict[]} verdicts
+ * @param {string} outFile
+ */
+function writeResultJson(verdicts, outFile) {
+  const payload = {
+    tool: 'llrt-analyzer',
+    generatedTiers: verdicts.some((v) => v.ranLocal) ? ['static', 'local'] : ['static'],
+    summary: {
+      total: verdicts.length,
+      switch: verdicts.filter((v) => v.recommendation === 'switch').length,
+      incompatible: verdicts.filter((v) => v.recommendation === 'incompatible').length,
+      unknown: verdicts.filter((v) => v.recommendation === 'unknown').length,
+    },
+    llrtCandidates: verdicts,
+  }
+  fs.writeFileSync(outFile, `${JSON.stringify(payload, null, 2)}\n`)
+  return payload
+}
+
+module.exports = { discoverFromServerless, writeResultJson }

package/src/smart-ci-check.js

@@ -0,0 +1,34 @@
+// @ts-check
+'use strict'
+/**
+ * smart-ci validator adapter (bead sci-xwk.34). Wraps the analyzer to return
+ * smart-ci's canonical validator shape so it can slot into src/validate/index.js
+ * behind a `checks.llrtCompat` toggle. Wiring (one line in the main CLI):
+ *
+ *   // src/validate/llrt-compat.js
+ *   module.exports = require('llrt-analyzer/src/smart-ci-check')
+ *   // src/validate/index.js
+ *   if (checks.llrtCompat) results.push(await require('./llrt-compat').validateLlrtCompatibility({ projectDir, functions }))
+ */
+const { analyzeService } = require('./index')
+
+/**
+ * @param {{ projectDir: string, functions?: {fn:string,entryPoint:string,handlerExport?:string}[], tiers?: string[] }} input
+ * @returns {Promise<{ valid: boolean, errors: {check:string, entryPoint:string, file?:string, error:string, fatal?:boolean}[], verified: string[] }>}
+ */
+async function validateLlrtCompatibility(input) {
+  const verdicts = await analyzeService({ projectDir: input.projectDir, functions: input.functions, tiers: input.tiers || ['static'] })
+  const errors = []
+  const verified = []
+  for (const v of verdicts) {
+    for (const b of v.blockers) {
+      errors.push({ check: 'llrt-compat', entryPoint: v.fn, file: b.file, error: `${b.api}: ${b.fix}`, fatal: b.fatal })
+    }
+    // A recommendation of "switch" is a non-fatal informational signal that the
+    // function is LLRT-ready (a candidate to flip for faster cold starts).
+    if (v.recommendation === 'switch' || v.recommendation === 'compatible-but-not-recommended') verified.push(v.fn)
+  }
+  return { valid: errors.every((e) => !e.fatal), errors, verified }
+}
+
+module.exports = { validateLlrtCompatibility }

package/src/static-scan.js

@@ -0,0 +1,195 @@
+// @ts-check
+'use strict'
+/**
+ * Tier-1 static scan (beads sci-xwk.7–.13): classify node: builtins, guard
+ * against disallowed API usage (runs every time), resolve the AWS-SDK bundle,
+ * flag known-bad npm + compute-heavy workloads, and attach a concrete fix to
+ * every finding. Assembles a partial FunctionVerdict (no execution required).
+ */
+const fs = require('fs')
+const path = require('path')
+const { resolveImportGraph } = require('./import-graph')
+const kb = require('./knowledge-base')
+const { emptyVerdict } = require('./verdict')
+
+/** Specific unsupported CALLS inside otherwise-partial modules + hard guards.
+ * This scan runs on every invocation regardless of any cached verdict, so a
+ * pure-code change that introduces an unsupported API is caught immediately. */
+const DISALLOWED = [
+  { re: /\b(?:https?|node:https?)\s*\.\s*createServer\s*\(/, api: 'http.createServer', fix: 'node:http server is not implemented in LLRT — this handler cannot host a server; keep it on Node.' },
+  { re: /\bnew\s+Worker\s*\(/, api: 'worker_threads.Worker', fix: 'worker_threads is unsupported in LLRT — remove the worker or keep this function on Node.' },
+  { re: /\bcrypto\s*\.\s*createDiffieHellman\s*\(/, api: 'crypto.createDiffieHellman', fix: 'no LLRT equivalent — move Diffie-Hellman off this path or keep on Node.' },
+  { re: /\bcrypto\s*\.\s*generatePrime(Sync)?\s*\(/, api: 'crypto.generatePrime', fix: 'not available under LLRT — keep on Node.' },
+  { re: /\brequire\(\s*['"]node:vm['"]\s*\)|from\s+['"]node:vm['"]/, api: 'node:vm', fix: 'node:vm is unsupported in LLRT.' },
+  { re: /\bchild_process\s*\.\s*(exec|spawn|fork)\s*\(/, api: 'child_process', fix: 'child_process is (effectively) unsupported in LLRT — keep on Node.' },
+]
+
+/** @param {string} name */
+function fixForBuiltin(name) {
+  const map = {
+    http: 'node:http is not implemented in LLRT — use global fetch, or keep this function on Node.',
+    https: 'node:https is not implemented — use global fetch, or keep on Node.',
+    net: 'raw sockets are not implemented in LLRT.',
+    tls: 'node:tls is not implemented — outbound TLS goes through fetch.',
+    worker_threads: 'worker_threads is unsupported in LLRT (no multithreading).',
+    child_process: 'child_process is unsupported for LLRT handlers.',
+    vm: 'node:vm is unsupported in LLRT.',
+    cluster: 'node:cluster is unsupported (single-invocation Lambda anyway).',
+    http2: 'node:http2 is unsupported in LLRT.',
+    dgram: 'node:dgram (UDP) is unsupported in LLRT.',
+    dns: 'node:dns is unsupported in LLRT.',
+  }
+  return map[name] || `node:${name} is not available under LLRT — keep this function on Node or remove the dependency.`
+}
+
+/**
+ * @param {{ entryPoint: string, projectDir?: string, llrtVersion?: string, fn?: string }} input
+ * @returns {import('./verdict').FunctionVerdict}
+ */
+function staticScan(input) {
+  const version = input.llrtVersion || kb.ORG_PINNED_LLRT_VERSION
+  const projectDir = input.projectDir || path.dirname(input.entryPoint)
+  const v = emptyVerdict(input.fn || path.basename(input.entryPoint), { llrtVersion: version })
+
+  const graph = resolveImportGraph(input.entryPoint, { projectDir })
+
+  // --- (sci-xwk.7) node: builtin classification ---
+  for (const b of graph.builtins) {
+    const status = kb.builtinStatus(b.name, version)
+    if (status === 'unsupported' || status === 'planned') {
+      v.blockers.push({ api: `node:${b.name}`, file: b.file, via: b.via, fatal: true, fix: fixForBuiltin(b.name) })
+    } else if (status === 'partial') {
+      v.warnings.push({ kind: 'partial-api', file: b.file, note: `node:${b.name} is partial under LLRT — ${kb.builtinNote(b.name, version) || 'confirm the specific calls by running it'}`, fix: 'run the local call-comparison (Tier 2) to confirm the exact APIs used behave identically.' })
+    } else if (status === 'supported') {
+      v.verified.push(`node:${b.name}`)
+    } else {
+      v.warnings.push({ kind: 'partial-api', file: b.file, note: `node:${b.name} not in the LLRT ${version} compat table — treat as unknown; run to confirm.` })
+    }
+  }
+
+  // --- (sci-xwk.8) disallowed-API scan (every run guard) — only reachable first-party files ---
+  const firstParty = graph.firstPartyFiles && graph.firstPartyFiles.length ? graph.firstPartyFiles : [input.entryPoint]
+  for (const hit of disallowedApiScan(firstParty, projectDir)) {
+    if (!v.blockers.some((b) => b.api === hit.api)) {
+      v.blockers.push({ api: hit.api, file: hit.file, fatal: true, fix: hit.fix })
+    }
+  }
+
+  // --- known-quirks scan: confirmed BEHAVIORAL breaks that plain import/builtin
+  // analysis can't see (e.g. hono/cors emptying the body under LLRT). Seeded
+  // from empirical findings so the static tier + deploy guard catch them cheaply. ---
+  for (const hit of knownQuirksScan(firstParty, projectDir, version)) {
+    if (hit.severity === 'blocker') {
+      if (!v.blockers.some((b) => b.api === hit.api)) {
+        v.blockers.push({ api: hit.api, file: hit.file, via: hit.id, fatal: true, fix: hit.fix })
+      }
+    } else if (!v.warnings.some((w) => w.note === hit.note)) {
+      v.warnings.push({ kind: 'partial-api', file: hit.file, note: `${hit.api}: ${hit.note}`, fix: hit.fix })
+    }
+  }
+
+  // --- (sci-xwk.9) AWS SDK bundle (only user-facing client-/lib- packages;
+  // @aws-sdk/core, @smithy/*, credential-provider-* are SDK internals covered
+  // by the bundle, not something the user bundles-in) ---
+  const clients = graph.awsSdkClients.filter((c) => /^@aws-sdk\/(client|lib)-/.test(c))
+  const sdk = kb.resolveSdkBundle(clients, version)
+  v.sdkBundle = sdk.bundle
+  v.bundleIn = sdk.bundleIn
+  for (const c of sdk.bundleIn) {
+    v.warnings.push({ kind: 'sdk-bundle', note: `${c} is not in the LLRT ${sdk.bundle} bundle`, fix: `bundle ${c} INTO the artifact (do not mark it external), or use the -full-sdk bundle.` })
+  }
+
+  // --- (sci-xwk.10) known-bad npm + workload heuristic ---
+  const knownBad = kb.loadKnownBad().packages
+  for (const p of graph.npmPkgs) {
+    const bad = knownBad[p.name]
+    if (!bad) continue
+    if (bad.status === 'blocker') v.blockers.push({ api: p.name, file: p.file, fatal: true, fix: bad.reason })
+    else v.warnings.push({ kind: 'known-bad', file: p.file, note: `${p.name}: ${bad.reason}`, fix: bad.reason })
+  }
+  for (const w of workloadHeuristic(firstParty, projectDir)) v.warnings.push(w)
+
+  // --- (sci-xwk.12) staticTier ---
+  const hasFatal = v.blockers.some((b) => b.fatal)
+  const hasPartial = v.warnings.some((w) => w.kind === 'partial-api')
+  v.staticTier = hasFatal ? 'likely-incompatible' : hasPartial ? 'unknown' : 'likely-compatible'
+  v.recommendation = hasFatal ? 'incompatible' : 'unknown'
+  v.valid = !hasFatal
+  return v
+}
+
+/** Match disallowed patterns across the given (reachable, first-party) files. */
+function disallowedApiScan(files, projectDir) {
+  const hits = []
+  for (const file of files) {
+    const text = readSafe(file)
+    if (text == null) continue
+    for (const d of DISALLOWED) {
+      if (d.re.test(text)) hits.push({ api: d.api, file: relOf(projectDir, file), fix: d.fix })
+    }
+  }
+  return hits
+}
+
+/**
+ * Match confirmed behavioral quirks (from the versioned known-quirks DB) across
+ * reachable first-party files. Each signature is a source regex; a hit carries
+ * the root cause + fix. Signatures live in data/known-quirks.<version>.json so
+ * findings accrete without code changes.
+ */
+function knownQuirksScan(files, projectDir, version) {
+  const { quirks } = kb.loadKnownQuirks(version)
+  if (!quirks || !quirks.length) return []
+  const compiled = quirks
+    .map((q) => {
+      try {
+        return { ...q, re: new RegExp(q.signature) }
+      } catch (_) {
+        return null
+      }
+    })
+    .filter(Boolean)
+  const hits = []
+  const seen = new Set()
+  for (const file of files) {
+    const text = readSafe(file)
+    if (text == null) continue
+    for (const q of compiled) {
+      if (seen.has(q.id)) continue
+      if (q.re.test(text)) {
+        seen.add(q.id)
+        hits.push({ id: q.id, api: q.api, severity: q.severity || 'warning', note: q.note, fix: q.fix, file: relOf(projectDir, file) })
+      }
+    }
+  }
+  return hits
+}
+
+/** Very light compute-heavy heuristic: nested loops in a reachable file. */
+function workloadHeuristic(files, projectDir) {
+  const out = []
+  for (const file of files) {
+    const text = readSafe(file)
+    if (text == null) continue
+    const nested = /for\s*\([^)]*\)\s*\{[\s\S]{0,400}?for\s*\(/.test(text) || /while\s*\([^)]*\)\s*\{[\s\S]{0,400}?for\s*\(/.test(text)
+    if (nested) {
+      /** @type {import('./verdict').Warning} */
+      const w = { kind: 'workload', file: relOf(projectDir, file), note: 'nested loops detected — LLRT has no JIT and may be SLOWER for CPU-bound work here', fix: 'compatible, but measure before switching; consider keeping compute-heavy functions on Node.' }
+      out.push(w)
+    }
+  }
+  return out
+}
+
+function readSafe(file) {
+  try {
+    return fs.readFileSync(file, 'utf8')
+  } catch (_) {
+    return null
+  }
+}
+function relOf(projectDir, file) {
+  return projectDir ? path.relative(projectDir, file) : file
+}
+
+module.exports = { staticScan, disallowedApiScan, workloadHeuristic, knownQuirksScan }

package/src/verdict.js

@@ -0,0 +1,133 @@
+// @ts-check
+'use strict'
+/**
+ * Verdict contract (bead sci-xwk.2). The stable shape every tier + both
+ * consumers (serverless plugin, smart-ci validator) depend on. See spec §3.
+ */
+
+/**
+ * @typedef {Object} Blocker
+ * @property {string} api        Offending API/module (e.g. 'node:http')
+ * @property {string} [file]     Where it was found
+ * @property {string} [via]      Dependency chain (e.g. 'undici')
+ * @property {boolean} fatal
+ * @property {string} fix        Concrete remedy
+ */
+/**
+ * @typedef {Object} Warning
+ * @property {'workload'|'partial-api'|'sdk-bundle'|'known-bad'} kind
+ * @property {string} [file]
+ * @property {string} note
+ * @property {string} [fix]
+ */
+/**
+ * @typedef {Object} CallDiff
+ * @property {string} event
+ * @property {string} path
+ * @property {*} node
+ * @property {*} llrt
+ */
+/**
+ * @typedef {Object} Provenance
+ * @property {string} tier            highest tier that ran: 'static'|'local'|'deploy'
+ * @property {string} [hostPlatform]  where the local run executed (e.g. 'darwin')
+ * @property {string} [hostArch]      e.g. 'arm64'
+ * @property {string} [targetPlatform] Lambda target (always 'linux')
+ * @property {string} [targetArch]    Lambda target arch (default 'arm64')
+ * @property {boolean} [hostMatchesTarget]
+ * @property {number} [corpusSize]    number of events the local tier ran
+ * @property {boolean} [cached]       verdict served from the persist cache
+ */
+/**
+ * @typedef {Object} FunctionVerdict
+ * @property {string} fn
+ * @property {'switch'|'incompatible'|'compatible-but-not-recommended'|'unknown'} recommendation
+ * @property {'high'|'medium'|'low'} confidence  how much to trust this verdict
+ * @property {boolean} valid
+ * @property {'likely-compatible'|'likely-incompatible'|'unknown'} staticTier
+ * @property {boolean} ranLocal
+ * @property {boolean} ranDeploy
+ * @property {'no-sdk'|'std-sdk'|'full-sdk'} sdkBundle
+ * @property {string[]} bundleIn
+ * @property {{ node: number|null, llrt: number|null, ratio: number|null, measured: boolean }} coldStartDeltaMs
+ * @property {Provenance} provenance
+ * @property {Blocker[]} blockers
+ * @property {Warning[]} warnings
+ * @property {CallDiff[]} diffs
+ * @property {string} llrtVersion
+ * @property {string[]} verified
+ */
+
+const { ORG_PINNED_LLRT_VERSION } = require('./knowledge-base')
+
+/**
+ * @param {string} fn
+ * @param {Partial<FunctionVerdict>} [over]
+ * @returns {FunctionVerdict}
+ */
+function emptyVerdict(fn, over = {}) {
+  return {
+    fn,
+    recommendation: 'unknown',
+    confidence: 'low',
+    valid: true,
+    staticTier: 'unknown',
+    ranLocal: false,
+    ranDeploy: false,
+    sdkBundle: 'no-sdk',
+    bundleIn: [],
+    coldStartDeltaMs: { node: null, llrt: null, ratio: null, measured: false },
+    provenance: { tier: 'static' },
+    blockers: [],
+    warnings: [],
+    diffs: [],
+    llrtVersion: ORG_PINNED_LLRT_VERSION,
+    verified: [],
+    ...over,
+  }
+}
+
+/**
+ * Decide the recommendation from the accumulated evidence (bead sci-xwk.25).
+ * Empirical (local run) is the source of truth: statically-ambiguous functions
+ * are decided by actually running them.
+ * @param {FunctionVerdict} v
+ * @returns {FunctionVerdict}
+ */
+function finalizeRecommendation(v) {
+  const hasFatal = v.blockers.some((b) => b.fatal)
+  const hasWorkloadWarn = v.warnings.some((w) => w.kind === 'workload')
+  const localClean = v.ranLocal && v.diffs.length === 0 && !v.blockers.some((b) => b.fatal)
+
+  /** @type {FunctionVerdict['recommendation']} */
+  let rec = 'unknown'
+  if (hasFatal) rec = 'incompatible'
+  else if (localClean) rec = hasWorkloadWarn ? 'compatible-but-not-recommended' : 'switch'
+  else if (v.ranLocal && v.diffs.length > 0) rec = 'incompatible'
+  else if (v.staticTier === 'likely-compatible') rec = hasWorkloadWarn ? 'compatible-but-not-recommended' : 'unknown'
+  else rec = 'unknown'
+
+  v.recommendation = rec
+  v.valid = !hasFatal
+  v.confidence = computeConfidence(v)
+  return v
+}
+
+/**
+ * How much to trust the verdict.
+ * - static only            → 'low'  (we did not actually run it)
+ * - ran local, host≠target → 'medium' (verified on the host arch/OS, not Lambda's linux)
+ * - ran local, host=target → 'high'
+ * A cached verdict keeps whatever confidence it was stored with.
+ * @param {FunctionVerdict} v
+ * @returns {FunctionVerdict['confidence']}
+ */
+function computeConfidence(v) {
+  if (v.provenance && v.provenance.cached) return v.confidence || 'medium'
+  if (v.ranDeploy) return 'high'
+  if (!v.ranLocal) return 'low'
+  const p = /** @type {Provenance} */ (v.provenance || {})
+  return p.hostMatchesTarget === false ? 'medium' : 'high'
+}
+
+module.exports = { emptyVerdict, finalizeRecommendation }