@davidwells/llrt-analyzer 0.1.0

package/src/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// @ts-check
+'use strict'
+/**
+ * llrt-analyzer CLI.
+ *
+ *   llrt-analyzer <entryFile|serviceDir> [--local] [--project <dir>] [--fn <name>] [--json]
+ *   llrt-analyzer init                       scaffold the serverless.yml snippet
+ *   llrt-analyzer publish-layer [options]    publish the LLRT layer + optionally write SSM
+ *   llrt-analyzer --help
+ *
+ * The analyze path runs the static tier (add --local for the decisive
+ * run-under-LLRT tier) and prints a readable verdict + fixes + cold-start win.
+ */
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { spawnSync } = require('child_process')
+const { analyzeFunction, analyzeService, ORG_PINNED_LLRT_VERSION } = require('./index')
+const { download, sha256File } = require('./binary-manager')
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    if (a === '--help' || a === '-h') args.flags.help = true
+    else if (a === '--json') args.flags.json = true
+    else if (a === '--local') args.flags.local = true
+    else if (a === '--no-cache') args.flags.cache = false
+    else if (a === '--project') args.flags.project = argv[(i += 1)]
+    else if (a === '--fn') args.flags.fn = argv[(i += 1)]
+    else if (a === '--handler-export') args.flags.handlerExport = argv[(i += 1)]
+    else if (a === '--out') args.flags.out = argv[(i += 1)]
+    else if (a === '--cache-file') args.flags.cacheFile = argv[(i += 1)]
+    else if (a === '--arch') args.flags.arch = argv[(i += 1)]
+    else if (a === '--region') args.flags.region = argv[(i += 1)]
+    else if (a === '--profile') args.flags.profile = argv[(i += 1)]
+    else if (a === '--layer-name') args.flags.layerName = argv[(i += 1)]
+    else if (a === '--ssm') args.flags.ssm = argv[(i += 1)]
+    else if (a === '--stage') args.flags.stage = argv[(i += 1)]
+    else args._.push(a)
+  }
+  return args
+}
+
+const HELP = `llrt-analyzer — can this Lambda function run on AWS LLRT (~10x faster cold starts)?
+
+Usage:
+  llrt-analyzer <entryFile|serviceDir> [options]   analyze one function or a whole service
+  llrt-analyzer init                               print the serverless.yml snippet to flip functions
+  llrt-analyzer publish-layer [options]            publish the LLRT layer (+ optionally write its ARN to SSM)
+
+Analyze options:
+  --local           Run the decisive tier: actually execute under the LLRT binary and diff behavior.
+  --project <dir>   Project root (for relative file paths). Default: entry's dir.
+  --fn <name>       Function name label. Default: entry basename.
+  --out <file>      Write machine-readable result.json (service mode).
+  --json            Emit the raw FunctionVerdict JSON.
+  --no-cache        Ignore the local-tier result cache.
+  --cache-file <f>  Use a specific cache store (default ~/.smart-ci/llrt/verdict-cache.json).
+
+publish-layer options:
+  --arch <arm64|x64>   Layer architecture (default arm64).
+  --region <region>    AWS region (default us-east-1).
+  --profile <name>     AWS profile.
+  --layer-name <name>  Layer name (default llrt-<arch>).
+  --ssm <param>        Also write the published ARN to this SSM parameter.
+
+Example:
+  llrt-analyzer services/mcp-gateway --local --out result.json
+`
+
+async function main() {
+  const { _, flags } = parseArgs(process.argv.slice(2))
+  if (flags.help || _.length === 0) {
+    process.stdout.write(HELP)
+    return
+  }
+  if (_[0] === 'init') return cmdInit()
+  if (_[0] === 'publish-layer') return cmdPublishLayer(flags)
+
+  const target = path.resolve(_[0])
+  const tiers = flags.local ? ['static', 'local'] : ['static']
+  const isDir = fs.existsSync(target) && fs.statSync(target).isDirectory()
+
+  // Whole-service mode: a directory -> discover functions from serverless.yml.
+  if (isDir) {
+    const verdicts = await analyzeService({ projectDir: target, tiers, resultFile: flags.out, cache: flags.cache, cacheFile: flags.cacheFile })
+    if (!verdicts.length) {
+      process.stderr.write(`No functions discovered in ${target} (need a serverless.yml with functions).\n`)
+      process.exit(2)
+    }
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(verdicts, null, 2)}\n`)
+      return
+    }
+    for (const v of verdicts) process.stdout.write(renderReport(v))
+    if (flags.out) process.stdout.write(`\nresult.json written to ${flags.out}\n`)
+    return
+  }
+
+  // Single-function mode.
+  const entryPoint = target
+  const projectDir = flags.project ? path.resolve(flags.project) : path.dirname(entryPoint)
+  const verdict = await analyzeFunction({ entryPoint, projectDir, fn: flags.fn, tiers, handlerExport: flags.handlerExport, cache: flags.cache, cacheFile: flags.cacheFile })
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(verdict, null, 2)}\n`)
+    return
+  }
+  process.stdout.write(renderReport(verdict))
+}
+
+function renderReport(v) {
+  const icon = { switch: '🟢', 'compatible-but-not-recommended': '🟡', unknown: '⚪', incompatible: '🔴' }[v.recommendation]
+  const lines = []
+  lines.push('')
+  lines.push(`${icon} ${v.fn}: ${v.recommendation.toUpperCase()}  (LLRT ${v.llrtVersion}, confidence: ${v.confidence}, static tier: ${v.staticTier})`)
+  lines.push(`   sdk bundle: ${v.sdkBundle}${v.bundleIn.length ? `  bundleIn: ${v.bundleIn.join(', ')}` : ''}`)
+  const cs = v.coldStartDeltaMs
+  if (cs && cs.measured) {
+    lines.push(`   cold start (init): node ~${cs.node}ms → llrt ~${cs.llrt}ms${cs.ratio ? `  (${cs.ratio}× faster)` : ''}`)
+  }
+  if (v.provenance && v.provenance.tier === 'local' && v.provenance.hostMatchesTarget === false) {
+    lines.push(`   ⚠ ran on ${v.provenance.hostPlatform}/${v.provenance.hostArch}; Lambda is ${v.provenance.targetPlatform}/${v.provenance.targetArch} → confidence: ${v.confidence}`)
+  }
+  if (v.provenance && v.provenance.cached) lines.push('   (result served from cache — inputs unchanged)')
+  if (v.verified.length) lines.push(`   verified: ${v.verified.join(', ')}`)
+  if (v.blockers.length) {
+    lines.push('   BLOCKERS:')
+    for (const b of v.blockers) lines.push(`     ✗ ${b.api}${b.via && b.via !== '(direct)' ? ` (via ${b.via})` : ''}${b.file ? `  [${b.file}]` : ''}\n         fix: ${b.fix}`)
+  }
+  if (v.warnings.length) {
+    lines.push('   WARNINGS:')
+    for (const w of v.warnings) lines.push(`     ! ${w.note}${w.fix ? `\n         fix: ${w.fix}` : ''}`)
+  }
+  if (v.diffs && v.diffs.length) {
+    lines.push(`   BEHAVIORAL DIFFS (Node vs LLRT — same input, different output):`)
+    for (const d of v.diffs) {
+      lines.push(`     ≠ ${d.event} ${d.path}`)
+      if (d.hint) lines.push(`         ${d.hint}`)
+    }
+  }
+  if (v.recommendation === 'switch' || v.recommendation === 'compatible-but-not-recommended') {
+    lines.push(`   → to flip: add \`llrt: true\` to the ${v.fn} function in serverless.yml`)
+  }
+  if (v.staticTier !== 'likely-incompatible' && !v.ranLocal) {
+    lines.push('   (static tier only — run the local call-comparison for a definitive verdict)')
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+/** `init` — print the serverless.yml snippet (non-destructive; paste it in). */
+function cmdInit() {
+  const snippet = `# --- llrt-analyzer: flip functions to AWS LLRT for ~10x faster cold starts ---
+plugins:
+  - serverless-llrt-analyzer
+
+custom:
+  llrt:
+    # Publish the layer once with:  llrt-analyzer publish-layer --ssm /my-svc/\${self:provider.stage}/llrt-layer-arn
+    layerArn: \${ssm:/my-svc/\${self:provider.stage}/llrt-layer-arn}
+    verify: true        # fail the deploy if a flagged function is LLRT-incompatible
+
+functions:
+  # add \`llrt: true\` to any function you want on LLRT (mixed-runtime is fine):
+  myFunction:
+    handler: src/handler.main
+    llrt: true
+`
+  process.stdout.write(snippet)
+  process.stdout.write('\n# Then run `llrt-analyzer <serviceDir> --local` to confirm each flagged function.\n')
+}
+
+/** `publish-layer` — download the LLRT lambda bootstrap, publish it as a layer,
+ * print the ARN, and optionally write it to SSM. Wraps the manual curl→publish→SSM dance. */
+async function cmdPublishLayer(flags) {
+  const arch = flags.arch === 'x64' ? 'x64' : 'arm64'
+  const region = flags.region || 'us-east-1'
+  const version = ORG_PINNED_LLRT_VERSION
+  const layerName = flags.layerName || `llrt-${arch}`
+  const asset = `llrt-lambda-${arch}.zip`
+  const url = `https://github.com/awslabs/llrt/releases/download/v${version}/${asset}`
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'llrt-layer-'))
+  const zip = path.join(tmp, asset)
+
+  process.stderr.write(`[publish-layer] downloading ${asset} @ v${version}\n`)
+  await download(url, zip)
+  process.stderr.write(`[publish-layer] sha256(${asset}) = ${sha256File(zip)}\n`)
+
+  const runtimes = 'provided.al2023'
+  const awsArgs = [
+    'lambda', 'publish-layer-version',
+    '--layer-name', layerName,
+    '--zip-file', `fileb://${zip}`,
+    '--compatible-architectures', arch,
+    '--compatible-runtimes', runtimes,
+    '--description', `AWS LLRT ${version} bootstrap (${arch})`,
+    '--region', region,
+    '--query', 'LayerVersionArn', '--output', 'text',
+  ]
+  if (flags.profile) awsArgs.push('--profile', flags.profile)
+  process.stderr.write(`[publish-layer] aws ${awsArgs.join(' ')}\n`)
+  const pub = spawnSync('aws', awsArgs, { encoding: 'utf8' })
+  if (pub.status !== 0) {
+    process.stderr.write(`[publish-layer] publish failed:\n${pub.stderr || pub.stdout}\n`)
+    process.exit(1)
+  }
+  const arn = (pub.stdout || '').trim()
+  process.stdout.write(`${arn}\n`)
+
+  if (flags.ssm) {
+    const ssmArgs = ['ssm', 'put-parameter', '--name', flags.ssm, '--type', 'String', '--overwrite', '--value', arn, '--region', region]
+    if (flags.profile) ssmArgs.push('--profile', flags.profile)
+    const put = spawnSync('aws', ssmArgs, { encoding: 'utf8' })
+    if (put.status !== 0) {
+      process.stderr.write(`[publish-layer] wrote layer but SSM put failed:\n${put.stderr || put.stdout}\n`)
+      process.exit(1)
+    }
+    process.stderr.write(`[publish-layer] wrote ARN to SSM ${flags.ssm}\n`)
+  } else {
+    process.stderr.write(`[publish-layer] set custom.llrt.layerArn to the ARN above (or re-run with --ssm <param>).\n`)
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`llrt-analyzer error: ${err && err.stack ? err.stack : err}\n`)
+  process.exit(1)
+})

package/src/cold-start.js

@@ -0,0 +1,51 @@
+// @ts-check
+'use strict'
+/**
+ * Cold-start init benchmark (idea #3).
+ *
+ * The whole value prop is "~10x faster cold starts", but the verdict never
+ * showed a number. This measures the dominant cold-start cost — interpreter
+ * startup + module init — by spawning the verify bundle with LLRT_INIT_ONLY=1
+ * (which imports everything then exits BEFORE running the handler) under Node
+ * and under the LLRT binary, and timing wall-clock. We take the MIN over a few
+ * samples (least noisy = closest to the machine's best case) and report the
+ * ratio. This is a proxy for the real Lambda Init Duration; the opt-in deploy
+ * tier (deploy-verify.js) measures the real thing.
+ */
+const { spawnSync } = require('child_process')
+
+/**
+ * @param {{ cmd: string, bundleFile: string, samples?: number, timeoutMs?: number }} input
+ * @returns {number|null} best-case init time in ms, or null if it never succeeded
+ */
+function timeInit(input) {
+  const samples = input.samples || 5
+  let best = null
+  for (let i = 0; i < samples; i += 1) {
+    const start = Date.now()
+    const res = spawnSync(input.cmd, [input.bundleFile], {
+      encoding: 'utf8',
+      timeout: input.timeoutMs || 20000,
+      env: { ...process.env, LLRT_INIT_ONLY: '1', VERIFY_EVENT_FILE: '' },
+      maxBuffer: 8 * 1024 * 1024,
+    })
+    const ms = Date.now() - start
+    // Only count runs that actually reached the init-only exit cleanly.
+    if (res.status === 0 && (best === null || ms < best)) best = ms
+  }
+  return best
+}
+
+/**
+ * Measure Node vs LLRT init for a built verify bundle.
+ * @param {{ nodeCmd?: string, llrtBin: string, bundleFile: string, samples?: number }} input
+ * @returns {{ node: number|null, llrt: number|null, ratio: number|null, measured: boolean }}
+ */
+function measureColdStart(input) {
+  const node = timeInit({ cmd: input.nodeCmd || process.execPath, bundleFile: input.bundleFile, samples: input.samples })
+  const llrt = timeInit({ cmd: input.llrtBin, bundleFile: input.bundleFile, samples: input.samples })
+  const ratio = node != null && llrt != null && llrt > 0 ? Math.round((node / llrt) * 10) / 10 : null
+  return { node, llrt, ratio, measured: node != null && llrt != null }
+}
+
+module.exports = { measureColdStart, timeInit }

package/src/corpus.js

@@ -0,0 +1,116 @@
+// @ts-check
+'use strict'
+/**
+ * Verify corpus (beads sci-xwk.23 + .24). Events to replay under Node + LLRT.
+ * Fixtures first (deterministic, no PII): __fixtures__/llrt/<fn>/*.json or
+ * __fixtures__/llrt/*.json. Optional CloudWatch capture through a redaction
+ * pass. Falls back to a synthetic per-adapter event.
+ */
+const fs = require('fs')
+const path = require('path')
+
+const REDACT_KEY = [/authoriz/i, /secret/i, /token/i, /password/i, /passwd/i, /email/i, /api[-_]?key/i, /credential/i, /cookie/i, /session/i, /ssn/i]
+
+/** Deep-redact values of sensitive-looking keys. Returns a new object. */
+function redact(value) {
+  if (Array.isArray(value)) return value.map(redact)
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const k of Object.keys(value)) out[k] = REDACT_KEY.some((re) => re.test(k)) ? '__REDACTED__' : redact(value[k])
+    return out
+  }
+  return value
+}
+
+/** Minimal API Gateway v2 (HTTP API) event. */
+function synthApiGwV2(method, routePath) {
+  return {
+    version: '2.0',
+    routeKey: `${method} ${routePath}`,
+    rawPath: routePath,
+    rawQueryString: '',
+    headers: { 'content-type': 'application/json' },
+    requestContext: { http: { method, path: routePath, sourceIp: '127.0.0.1' }, requestId: 'verify', stage: '$default' },
+    isBase64Encoded: false,
+  }
+}
+
+const SYNTH = {
+  httpApi: [synthApiGwV2('GET', '/'), synthApiGwV2('GET', '/health')],
+  sqs: [{ Records: [{ messageId: 'verify', body: '{}', attributes: {}, messageAttributes: {} }] }],
+  eventbridge: [{ version: '0', 'detail-type': 'verify', source: 'verify', detail: {} }],
+  s3: [{ Records: [{ eventName: 'ObjectCreated:Put', s3: { bucket: { name: 'verify' }, object: { key: 'k' } } }] }],
+  generic: [{}],
+}
+
+/**
+ * @param {{ projectDir: string, fnName?: string, adapter?: keyof typeof SYNTH, explicit?: any[] }} input
+ * @returns {any[]}
+ */
+function loadCorpus(input) {
+  if (input.explicit && input.explicit.length) return input.explicit
+  const roots = [
+    input.fnName && path.join(input.projectDir, '__fixtures__', 'llrt', input.fnName),
+    path.join(input.projectDir, '__fixtures__', 'llrt'),
+  ].filter(Boolean)
+  for (const dir of roots) {
+    const events = readJsonDir(dir)
+    if (events.length) return events
+  }
+  return SYNTH[input.adapter || 'httpApi'] || SYNTH.generic
+}
+
+function readJsonDir(dir) {
+  let entries
+  try {
+    entries = fs.readdirSync(dir)
+  } catch (_) {
+    return []
+  }
+  const out = []
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue
+    try {
+      out.push(JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')))
+    } catch (_) {
+      /* skip malformed */
+    }
+  }
+  return out
+}
+
+/**
+ * Best-effort capture of recent invocation events from CloudWatch Logs, redacted.
+ * Requires @aws-sdk/client-cloudwatch-logs + AWS creds; throws a clear error
+ * otherwise (fixtures remain the default).
+ * @param {{ logGroup: string, limit?: number, region?: string }} input
+ * @returns {Promise<any[]>}
+ */
+async function captureFromCloudWatch(input) {
+  let CWL
+  try {
+    const modName = '@aws-sdk/client-cloudwatch-logs' // indirect so tsc/bundlers don't require it
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    CWL = require(modName)
+  } catch (_) {
+    throw new Error('captureFromCloudWatch requires @aws-sdk/client-cloudwatch-logs to be installed.')
+  }
+  const client = new CWL.CloudWatchLogsClient({ region: input.region })
+  const res = await client.send(
+    new CWL.FilterLogEventsCommand({ logGroupName: input.logGroup, limit: input.limit || 25, filterPattern: '' }),
+  )
+  const events = []
+  for (const e of res.events || []) {
+    const m = String(e.message || '')
+    const start = m.indexOf('{')
+    if (start < 0) continue
+    try {
+      events.push(redact(JSON.parse(m.slice(start))))
+    } catch (_) {
+      /* not JSON */
+    }
+  }
+  return events
+}
+
+module.exports = { loadCorpus, redact, synthApiGwV2, captureFromCloudWatch }

package/src/deploy-verify.js

@@ -0,0 +1,65 @@
+// @ts-check
+'use strict'
+/**
+ * Tier-3 deploy-verify (bead sci-xwk.33) — OPT-IN, heavy. The local tier
+ * (call-comparison) is the default and covers correctness with no side effects;
+ * this tier exists for the extra confidence of running on real Lambda + a real
+ * cold-start measurement. It is intentionally gated (slow, costs AWS).
+ *
+ * Flow: deploy the LLRT variant to an ISOLATED ephemeral stage (own sandbox
+ * resources), replay the corpus + run the service's integration tests, MEASURE
+ * cold starts (Node vs LLRT), then tear down. Deploy/teardown are delegated to
+ * the Serverless Framework via child_process; measurement is implemented here.
+ */
+const { spawnSync } = require('child_process')
+
+/**
+ * Measure cold-start Init Duration by invoking a deployed function with a fresh
+ * container N times (forcing cold starts via an env bump between calls is
+ * service-specific; here we read Init Duration from the tail logs of cold
+ * invocations). Requires @aws-sdk/client-lambda + creds.
+ * @param {{ functionName: string, region?: string, samples?: number }} input
+ * @returns {Promise<{ p50: number|null, samples: number[] }>}
+ */
+async function measureColdStart(input) {
+  let Lambda
+  try {
+    const mod = '@aws-sdk/client-lambda'
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    Lambda = require(mod)
+  } catch (_) {
+    throw new Error('measureColdStart requires @aws-sdk/client-lambda + AWS credentials.')
+  }
+  const client = new Lambda.LambdaClient({ region: input.region })
+  const samples = []
+  const n = input.samples || 10
+  for (let i = 0; i < n; i += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    const res = await client.send(new Lambda.InvokeCommand({ FunctionName: input.functionName, LogType: 'Tail', Payload: Buffer.from('{}') }))
+    const log = res.LogResult ? Buffer.from(res.LogResult, 'base64').toString('utf8') : ''
+    const m = log.match(/Init Duration: ([0-9.]+) ms/)
+    if (m) samples.push(Number(m[1]))
+  }
+  samples.sort((a, b) => a - b)
+  const p50 = samples.length ? samples[Math.floor(samples.length / 2)] : null
+  return { p50, samples }
+}
+
+/**
+ * Deploy the service to an ephemeral stage, run the caller's verify callback,
+ * then tear down. The heavy orchestration (sandbox resources) is service-owned;
+ * this wraps deploy/remove so a caller can run replay + integration tests + a
+ * cold-start measurement in between.
+ * @param {{ serviceDir: string, stage: string, verify: () => Promise<any> }} input
+ */
+async function withEphemeralStage(input) {
+  const deploy = spawnSync('npx', ['serverless', 'deploy', '--stage', input.stage], { cwd: input.serviceDir, encoding: 'utf8', stdio: 'inherit' })
+  if (deploy.status !== 0) throw new Error(`ephemeral deploy failed (stage ${input.stage})`)
+  try {
+    return await input.verify()
+  } finally {
+    spawnSync('npx', ['serverless', 'remove', '--stage', input.stage], { cwd: input.serviceDir, encoding: 'utf8', stdio: 'inherit' })
+  }
+}
+
+module.exports = { measureColdStart, withEphemeralStage }

package/src/diff.js

@@ -0,0 +1,113 @@
+// @ts-check
+'use strict'
+/**
+ * Semantic diff (bead sci-xwk.20). Compare a Node run vs an LLRT run:
+ *  - downstream calls compared by kind + service/command/method/url + input,
+ *    ignoring SDK-internal noise (LLRT ships a different SDK build);
+ *  - HTTP responses compared after normalizing a denylist of volatile fields.
+ * Returns diffs[]; empty = behaved identically.
+ */
+
+const VOLATILE_KEYS = [/date/i, /time/i, /timestamp/i, /requestid/i, /x-amz-/i, /etag/i, /^id$/i, /Id$/, /trace/i, /nonce/i]
+
+function isVolatileKey(k) {
+  return VOLATILE_KEYS.some((re) => re.test(String(k)))
+}
+
+/** Strip volatile keys + sort, recursively, for stable comparison. */
+function normalize(value) {
+  if (Array.isArray(value)) return value.map(normalize)
+  if (value && typeof value === 'object') {
+    const out = {}
+    for (const k of Object.keys(value).sort()) {
+      if (isVolatileKey(k)) continue
+      out[k] = normalize(value[k])
+    }
+    return out
+  }
+  return value
+}
+
+/** Canonical key for a downstream call (order-independent multiset compare). */
+function callKey(c) {
+  if (c.kind === 'aws') return `aws:${c.service}.${c.command}:${stable(normalize(c.input))}`
+  if (c.kind === 'fetch') return `fetch:${c.method}:${stripQueryVolatile(c.url)}:${c.body ? stable(c.body) : ''}`
+  return `other:${stable(c)}`
+}
+function stripQueryVolatile(url) {
+  try {
+    const u = new URL(url)
+    return `${u.origin}${u.pathname}`
+  } catch (_) {
+    return String(url).split('?')[0]
+  }
+}
+function stable(v) {
+  return typeof v === 'string' ? v : JSON.stringify(normalize(v))
+}
+
+/**
+ * @param {string} event  label for reporting
+ * @param {{ok:boolean,response?:any,calls:any[],error?:string}} node
+ * @param {{ok:boolean,response?:any,calls:any[],error?:string}} llrt
+ * @returns {import('./verdict').CallDiff[]}
+ */
+function diffRun(event, node, llrt) {
+  const diffs = []
+  // 1. one crashed, the other didn't
+  if (node.ok !== llrt.ok) {
+    diffs.push({ event, path: '$run', node: node.ok ? 'ok' : `error: ${node.error}`, llrt: llrt.ok ? 'ok' : `error: ${llrt.error}` })
+    return diffs // no point diffing further
+  }
+  if (!node.ok && !llrt.ok) return diffs // both failed the same way (attributed elsewhere)
+
+  // 2. downstream call multiset
+  const nk = (node.calls || []).map(callKey).sort()
+  const lk = (llrt.calls || []).map(callKey).sort()
+  if (stable(nk) !== stable(lk)) {
+    diffs.push({ event, path: '$calls', node: nk, llrt: lk })
+  }
+
+  // 3. response
+  const rn = stable(normalize(node.response))
+  const rl = stable(normalize(llrt.response))
+  if (rn !== rl) {
+    const d = { event, path: '$response', node: normalize(node.response), llrt: normalize(llrt.response) }
+    const hint = explainResponseDiff(d)
+    if (hint) d.hint = hint
+    diffs.push(d)
+  }
+  return diffs
+}
+
+/**
+ * Attribute well-understood LLRT behavioral diffs to a root cause + fix, so a
+ * `$response` diff isn't just raw JSON the user has to decode. Empirically
+ * discovered + verified on real Lambda (see docs/PILOT-mcp-gateway.md).
+ * @returns {string} explanation, or '' if the pattern isn't recognized
+ */
+function explainResponseDiff(d) {
+  const n = d.node && typeof d.node === 'object' ? d.node : {}
+  const l = d.llrt && typeof d.llrt === 'object' ? d.llrt : {}
+  const nodeBody = typeof n.body === 'string' ? n.body : ''
+  const llrtBody = typeof l.body === 'string' ? l.body : ''
+  // Same status, headers largely intact, but LLRT returns an empty body where
+  // Node returned one: LLRT 0.8.x does not implement Response.prototype.body
+  // (the ReadableStream getter returns undefined). Any framework that re-wraps
+  // a response via `new Response(res.body, init)` — e.g. Hono when middleware
+  // mutates headers post-handler (CORS) — then produces `new Response(undefined)`
+  // → empty body. `.text()`/`.arrayBuffer()` still work; only `.body` is missing.
+  if (nodeBody.length > 0 && llrtBody.length === 0 && n.statusCode === l.statusCode) {
+    return (
+      'LLRT dropped the response body (Node returned one). Root cause: LLRT 0.8.x ' +
+      'does not implement Response.prototype.body (ReadableStream) — it returns undefined. ' +
+      'Frameworks that re-wrap a response from res.body (Hono when header-mutating ' +
+      'middleware like CORS runs after the handler) yield an empty body under LLRT. ' +
+      'Fix: avoid reading Response#body (return the string/JSON directly, or drop the ' +
+      'post-handler header mutation), or keep this function on Node until LLRT ships it.'
+    )
+  }
+  return ''
+}
+
+module.exports = { diffRun, normalize, explainResponseDiff }

package/src/error-map.js

@@ -0,0 +1,38 @@
+// @ts-check
+'use strict'
+/**
+ * Error-signature -> offending API attribution (bead sci-xwk.21). Turns an
+ * opaque LLRT runtime error into an actionable blocker with a fix.
+ */
+const SIGNATURES = [
+  {
+    // esbuild bundled `import { X } from 'Y'` but LLRT's Y has no export X.
+    re: /Could not find export '([^']+)' in module '([^']+)'/i,
+    derive: (m) => ({
+      api: `node:${m[2]}.${m[1]}`,
+      fix: `LLRT's node:${m[2]} does not export "${m[1]}" — avoid that call (e.g. use a supported alternative) or keep this function on Node.`,
+    }),
+  },
+  { re: /\bhttp\b.*(not implemented|unsupported)|createServer is not a function/i, api: 'node:http', fix: 'node:http is not implemented in LLRT — use global fetch, or keep this function on Node.' },
+  { re: /createDiffieHellman is not a function/i, api: 'crypto.createDiffieHellman', fix: 'no LLRT equivalent — move Diffie-Hellman off this path or keep on Node.' },
+  { re: /generatePrime.*is not a function/i, api: 'crypto.generatePrime', fix: 'not available under LLRT — keep on Node.' },
+  { re: /(createCipheriv|createDecipheriv|scrypt|pbkdf2).*is not a function/i, api: 'crypto.<cipher/kdf>', fix: 'this crypto primitive is not available under LLRT — keep on Node or use a supported algorithm.' },
+  { re: /Worker is not (defined|a constructor)/i, api: 'worker_threads', fix: 'worker_threads is unsupported in LLRT.' },
+  { re: /Cannot find module|Unable to resolve|Unknown module|Module not found/i, api: 'module-resolution', fix: 'a dependency or builtin the handler imports is not available under LLRT — check the static blockers.' },
+  { re: /is not a function/i, api: 'unknown-api', fix: 'an API the handler calls is missing under LLRT — run with LLRT_ASYNC_HOOKS/verbose to locate it.' },
+]
+
+/**
+ * @param {string} errText
+ * @returns {{ api: string, fix: string }|null}
+ */
+function attributeError(errText) {
+  if (!errText) return null
+  for (const s of SIGNATURES) {
+    const m = errText.match(s.re)
+    if (m) return s.derive ? s.derive(m) : { api: s.api, fix: s.fix }
+  }
+  return null
+}
+
+module.exports = { attributeError }