@davidwells/llrt-analyzer 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# @davidwells/llrt-analyzer
+
+Decide — **per Lambda function** — whether it can run on [AWS LLRT](https://github.com/awslabs/llrt)
+(QuickJS, no JIT) for **~10x faster cold starts**, and help flip it. LLRT is not a
+Node drop-in (no `node:http`/`https`/`tls`, no `worker_threads`, partial
+`crypto`/`fs`/`stream`, pre-bundled AWS SDK subset), and you can't tell
+statically — so this tool **actually bundles the handler and runs it under both
+Node and the LLRT binary**, then diffs behavior. **If it runs identically, it
+recommends switching.**
+
+## Install
+
+```
+npm i -D @davidwells/llrt-analyzer   # CLI command is `llrt-analyzer`
+```
+
+## CLI
+
+```bash
+# One function
+llrt-analyzer services/mcp-gateway/src/app.ts --project services/mcp-gateway --fn api
+
+# One function, definitive (runs it under the real LLRT binary)
+llrt-analyzer services/mcp-gateway/src/app.ts --project services/mcp-gateway --fn api --local
+
+# Whole service (discovers functions from serverless.yml) + machine output
+llrt-analyzer services/mcp-gateway --local --out result.json
+
+# Scaffold the serverless.yml snippet, and publish the LLRT layer (+ write SSM)
+llrt-analyzer init
+llrt-analyzer publish-layer --arch arm64 --region us-east-1 --ssm /my-svc/prod/llrt-layer-arn
+```
+
+## Tiers
+
+1. **Static** (default, no binary) — resolves the transitive import graph and
+   flags `node:` blockers, a per-run disallowed-API guard, a **known-quirks**
+   scan (confirmed behavioral breaks — e.g. `hono/cors` emptying the body, or
+   `timingSafeEqual` — caught from source signatures, no run needed), the AWS-SDK
+   bundle, known-bad npm, and CPU-heavy workloads — each with a concrete fix.
+2. **Local call-comparison** (`--local`, the decisive tier) — bundles for LLRT
+   (aliasing `@aws-sdk`/`@smithy` to a recorder shim, no side effects), runs the
+   handler under **Node and LLRT** with `fetch` + SDK calls intercepted, and
+   diffs **semantically**. LLRT crashes are attributed to the exact missing API.
+   Also **measures the cold-start win** (node vs LLRT init) and stamps
+   **confidence + provenance** (see below). Results are **cached** by built-bundle
+   content, so repeat/CI runs are instant on unchanged inputs (`--no-cache` to
+   bypass).
+3. **Deploy-verify** (opt-in, heavy) — ephemeral-stage deploy + integration
+   tests + a real cold-start measurement. Gated; the local tier covers
+   correctness without a deploy.
+
+## Verdict
+
+`switch` · `compatible-but-not-recommended` (e.g. CPU-heavy) · `incompatible`
+(with the exact blocker + fix) · `unknown` (static-ambiguous — run `--local`).
+`result.json.llrtCandidates[]` is jq-able for CI.
+
+Every verdict carries a **`confidence`** (`high`/`medium`/`low`) and
+**`provenance`**: static-only is `low`; a local run on the **host** arch is
+`high`, but if the host ≠ Lambda's target (e.g. verified on darwin, Lambda is
+linux/arm64) it is downgraded to `medium` and the report says so — the tool
+never silently passes off a host-arch result as a Lambda guarantee. Local runs
+also report `coldStartDeltaMs` (`node`/`llrt`/`ratio`), the number that
+justifies the flip.
+
+## Known-quirks DB
+
+`data/known-quirks.<version>.json` holds confirmed **behavioral** LLRT breaks
+that plain import/builtin analysis can't see, each with a source-detectable
+signature so the static tier (and the deploy guard) flag them **before** a local
+run or deploy. Add to it as new quirks are found — findings accrete into cheap
+checks. The serverless plugin's guard runs the static tier, so it inherits these
+automatically.
+
+## Serverless plugin (flip a function)
+
+The Serverless Framework consumer ships as its own package,
+[`serverless-llrt-analyzer`](../serverless-llrt-analyzer) (depends on this core):
+
+```yaml
+plugins:
+  - serverless-llrt-analyzer
+custom:
+  llrt:
+    layerArn: arn:aws:lambda:us-east-1:xxxx:layer:llrt-arm64:1  # your LLRT layer
+    verify: true          # guard: fail deploy if a flagged fn is incompatible
+functions:
+  api:        { handler: src/app.handler, llrt: true }   # -> provided.al2023 + arm64 + LLRT layer
+  warmer:     { handler: src/warmer.warm, llrt: true }
+  processImg: { handler: src/img.handler }               # stays nodejs
+```
+
+Reverting is one line (remove `llrt: true`). Mixed-runtime services are
+first-class.
+
+## smart-ci integration
+
+- **Validator**: `@davidwells/llrt-analyzer/src/smart-ci-check` returns the canonical
+  `{ valid, errors:[{check:'llrt-compat',…}], verified }` shape; wire it into
+  `src/validate/index.js` behind a `checks.llrtCompat` toggle.
+- **Persistence** (`src/persist.js`): cache the "llrtable" verdict keyed on
+  `hash(bundle + lockfile + llrtVersion)`; re-verify only on change. The Tier-1
+  disallowed-API scan still runs every CI run as a guard.
+- **CI cadence** (consumer-configurable): (a) on-demand/opt-in, (b) a nightly
+  audit that opens "X is now LLRT-ready" PRs, (c) every changed candidate. Fold
+  `result.json.llrtCandidates` into `detect-changes.yml` via `jq`.
+
+## LLRT version pinning
+
+One org-wide pinned version (`ORG_PINNED_LLRT_VERSION`, currently `0.8.1-beta`).
+`scripts/refresh.js` regenerates the compat table from the LLRT repo; bumping the
+pin is deliberate and re-verifies all llrtable functions. The LLRT binary is
+downloaded from GitHub releases and **executed**, so it is verified against a
+pinned sha256 in `data/llrt-binary-checksums.<version>.json` — a mismatch aborts
+(an unlisted asset is allowed but logs its observed hash to pin).
+
+## When NOT to use LLRT
+
+Compute-heavy functions (big loops, large-data transforms, heavy hashing): LLRT
+has no JIT and can be **slower** than Node even when compatible — the analyzer
+warns (`compatible-but-not-recommended`).

package/data/compat-table.0.8.1-beta.json

@@ -0,0 +1,67 @@
+{
+  "llrtVersion": "0.8.1-beta",
+  "source": "https://github.com/awslabs/llrt#compatibility-matrix",
+  "_status_legend": {
+    "supported": "works",
+    "partial": "present but incomplete API surface \u2014 MUST run to confirm the specific calls used",
+    "planned": "not implemented yet (LLRT marks it) \u2014 treat as a blocker",
+    "unsupported": "will not work \u2014 blocker"
+  },
+  "builtins": {
+    "assert": "partial",
+    "async_hooks": "partial",
+    "buffer": "partial",
+    "child_process": "unsupported",
+    "cluster": "unsupported",
+    "console": "partial",
+    "crypto": "partial",
+    "dgram": "unsupported",
+    "diagnostics_channel": "unsupported",
+    "dns": "unsupported",
+    "domain": "unsupported",
+    "events": "partial",
+    "fs": "partial",
+    "fs/promises": "partial",
+    "http": "planned",
+    "http2": "unsupported",
+    "https": "planned",
+    "inspector": "unsupported",
+    "module": "partial",
+    "net": "planned",
+    "os": "partial",
+    "path": "partial",
+    "perf_hooks": "partial",
+    "process": "partial",
+    "punycode": "unsupported",
+    "querystring": "unsupported",
+    "readline": "unsupported",
+    "repl": "unsupported",
+    "stream": "partial",
+    "stream/web": "partial",
+    "string_decoder": "supported",
+    "sys": "unsupported",
+    "timers": "supported",
+    "timers/promises": "supported",
+    "tls": "planned",
+    "trace_events": "unsupported",
+    "tty": "unsupported",
+    "url": "partial",
+    "util": "partial",
+    "v8": "unsupported",
+    "vm": "unsupported",
+    "wasi": "unsupported",
+    "worker_threads": "unsupported",
+    "zlib": "partial"
+  },
+  "notes": {
+    "http": "node:http is not implemented; use fetch instead.",
+    "https": "node:https is not implemented; use fetch instead.",
+    "net": "raw sockets not implemented.",
+    "tls": "not implemented; outbound TLS is via fetch (TLS 1.2 default, LLRT_TLS_VERSION=1.3 opt-in).",
+    "crypto": "Hash/HMAC/randomBytes/randomUUID/randomFillSync present; createDiffieHellman, some ciphers and KDFs are NOT available. Run to confirm the exact fns used.",
+    "stream": "native LLRT implementation, not full Node stream compatibility.",
+    "worker_threads": "no multithreading.",
+    "child_process": "extremely limited; treat as unsupported for Lambda handlers.",
+    "querystring": "node:querystring is not resolvable in LLRT 0.8.1 (empirically verified)."
+  }
+}

package/data/known-bad.json

@@ -0,0 +1,16 @@
+{
+  "_note": "npm packages known to break under LLRT (QuickJS, no JIT, partial node API). status: 'blocker' (won't run) or 'warn' (works but risky/slow). 'reason' feeds the fix suggestion. Curated — extend as discovered.",
+  "packages": {
+    "sharp": { "status": "blocker", "reason": "native addon (node-gyp); LLRT has no native addon support" },
+    "canvas": { "status": "blocker", "reason": "native addon; unsupported under LLRT" },
+    "bcrypt": { "status": "blocker", "reason": "native addon; use bcryptjs (pure JS) or keep on Node" },
+    "puppeteer": { "status": "blocker", "reason": "spawns a browser via child_process; unsupported" },
+    "playwright": { "status": "blocker", "reason": "child_process + native; unsupported" },
+    "express": { "status": "blocker", "reason": "built on node:http server which is not implemented in LLRT" },
+    "koa": { "status": "blocker", "reason": "node:http server based; not implemented in LLRT" },
+    "ws": { "status": "blocker", "reason": "node:net/http upgrade; not implemented" },
+    "node-fetch": { "status": "warn", "reason": "prefer global fetch (built-in) under LLRT" },
+    "axios": { "status": "warn", "reason": "may use node:http adapter transitively; ensure the fetch/xhr adapter is used" },
+    "undici": { "status": "warn", "reason": "pulls node:http internals; prefer global fetch" }
+  }
+}

package/data/known-quirks.0.8.1-beta.json

@@ -0,0 +1,36 @@
+{
+  "llrtVersion": "0.8.1-beta",
+  "note": "Confirmed BEHAVIORAL incompatibilities that static import/builtin analysis alone cannot see — each with a source-detectable signature so the static tier (and the deploy guard) can flag them BEFORE a local run or deploy. Signatures are matched against reachable first-party files. Findings here were discovered empirically (and, where noted, verified on real Lambda); add to this file as new quirks are found so the knowledge accretes into cheap checks.",
+  "quirks": [
+    {
+      "id": "hono-cors-empty-body",
+      "signature": "(?:from\\s+|require\\(\\s*)[\"']hono/cors[\"']",
+      "files": "firstParty",
+      "severity": "blocker",
+      "api": "hono/cors (Response#body)",
+      "note": "Hono's cors() middleware mutates response headers AFTER the handler, forcing Hono to rebuild the response via new Response(res.body, init). LLRT 0.8.x does not implement Response.prototype.body (the getter returns undefined), so the rebuild drops the body — clients get the right status/headers but an EMPTY body. Verified on real Lambda: nodejs22.x keeps the body, provided.al2023+LLRT empties it.",
+      "fix": "Replace hono/cors with a prepared-headers CORS middleware: set the CORS headers via c.header() BEFORE next() (so they fold into the handler's response with no rebuild), and answer OPTIONS preflight with a body-less 204. See the serverless-llrt-analyzer README.",
+      "tracking": "https://github.com/awslabs/llrt/issues"
+    },
+    {
+      "id": "crypto-timing-safe-equal",
+      "signature": "\\btimingSafeEqual\\s*\\(",
+      "files": "firstParty",
+      "severity": "blocker",
+      "api": "node:crypto.timingSafeEqual",
+      "note": "LLRT 0.8.x node:crypto does not export timingSafeEqual — importing/calling it throws at runtime.",
+      "fix": "Use a pure-JS constant-time compare (XOR-accumulate over two equal-length buffers, length-check first) instead of timingSafeEqual.",
+      "tracking": "https://github.com/honojs/hono/issues/3914"
+    },
+    {
+      "id": "response-body-rewrap",
+      "signature": "new\\s+Response\\s*\\([^)]{0,80}\\.body\\b",
+      "files": "firstParty",
+      "severity": "warning",
+      "api": "Response.prototype.body",
+      "note": "Constructing a Response from another Response/Request .body relies on Response.prototype.body, which is undefined in LLRT 0.8.x — the resulting body is empty.",
+      "fix": "Avoid reading Response#body; pass the string/JSON body directly, or keep this function on Node until LLRT ships Response#body.",
+      "tracking": "https://github.com/awslabs/llrt/issues"
+    }
+  ]
+}

package/data/llrt-binary-checksums.0.8.1-beta.json

@@ -0,0 +1,9 @@
+{
+  "llrtVersion": "0.8.1-beta",
+  "algorithm": "sha256",
+  "note": "sha256 of the EXTRACTED llrt executable per release asset, pinned after review. The tool downloads and EXECUTES this binary, so downloads are verified against these hashes — a mismatch aborts (tamper/corruption). Assets not listed here are downloaded with a warning that logs the observed hash so a maintainer can pin it. Regenerate/extend with scripts/refresh-checksums.js.",
+  "binaries": {
+    "llrt-darwin-arm64-full-sdk.zip": "a63f3330d9a834fbc148c62f3ec8473e6a7af5a3215454285c0c7a1b9291d668",
+    "llrt-darwin-arm64-no-sdk.zip": "494da93c5d88fc464607fa2b5017f856f954409c4fa5049dabeb59a4c188e071"
+  }
+}

package/data/sdk-bundle.0.8.1-beta.json

@@ -0,0 +1,40 @@
+{
+  "llrtVersion": "0.8.1-beta",
+  "source": "https://github.com/awslabs/llrt#using-aws-sdk-v3-with-llrt",
+  "_note": "LLRT ships pre-bundled AWS SDK v3 clients. 'always' = in every bundle (mark external). 'std' = in the default (std-sdk) bundle. 'full' = only in the -full-sdk bundle. Anything not listed must be bundled INTO the artifact (bundleIn), not marked external.",
+  "always": [
+    "@smithy/",
+    "@aws-crypto/",
+    "@aws-sdk/credential-providers",
+    "@aws-sdk/lib-dynamodb",
+    "@aws-sdk/lib-storage",
+    "@aws-sdk/s3-presigned-post",
+    "@aws-sdk/s3-request-presigner",
+    "@aws-sdk/util-dynamodb"
+  ],
+  "std": [
+    "@aws-sdk/client-s3",
+    "@aws-sdk/client-dynamodb",
+    "@aws-sdk/client-dynamodb-streams",
+    "@aws-sdk/client-sqs",
+    "@aws-sdk/client-sns",
+    "@aws-sdk/client-eventbridge",
+    "@aws-sdk/client-kms",
+    "@aws-sdk/client-secrets-manager",
+    "@aws-sdk/client-sts",
+    "@aws-sdk/client-lambda",
+    "@aws-sdk/client-cloudwatch",
+    "@aws-sdk/client-cloudwatch-logs"
+  ],
+  "full": [
+    "@aws-sdk/client-ssm",
+    "@aws-sdk/client-cognito-identity-provider",
+    "@aws-sdk/client-api-gateway",
+    "@aws-sdk/client-apigatewayv2",
+    "@aws-sdk/client-step-functions",
+    "@aws-sdk/client-ses",
+    "@aws-sdk/client-sesv2",
+    "@aws-sdk/client-firehose",
+    "@aws-sdk/client-kinesis"
+  ]
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@davidwells/llrt-analyzer",
+  "version": "0.1.0",
+  "description": "Per-function analyzer that decides (statically + by actually running under LLRT) whether a Lambda function can switch to AWS LLRT for ~10x faster cold starts, and helps flip it.",
+  "main": "src/index.js",
+  "bin": {
+    "llrt-analyzer": "src/cli.js"
+  },
+  "files": [
+    "README.md",
+    "data/compat-table.0.8.1-beta.json",
+    "data/known-bad.json",
+    "data/known-quirks.0.8.1-beta.json",
+    "data/llrt-binary-checksums.0.8.1-beta.json",
+    "data/sdk-bundle.0.8.1-beta.json",
+    "src/binary-manager.js",
+    "src/build-for-llrt.js",
+    "src/cli.js",
+    "src/cold-start.js",
+    "src/corpus.js",
+    "src/deploy-verify.js",
+    "src/diff.js",
+    "src/error-map.js",
+    "src/import-graph.js",
+    "src/index.js",
+    "src/knowledge-base.js",
+    "src/local-compare.js",
+    "src/persist.js",
+    "src/run-under.js",
+    "src/runtime/aws-recorder.cjs",
+    "src/service.js",
+    "src/smart-ci-check.js",
+    "src/static-scan.js",
+    "src/verdict.js"
+  ],
+  "scripts": {
+    "test": "uvu src \".*\\.test\\.js$\"",
+    "types": "tsc"
+  },
+  "keywords": [
+    "llrt",
+    "aws-lambda",
+    "serverless",
+    "cold-start",
+    "quickjs",
+    "compatibility",
+    "runtime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavidWells/smart-ci.git",
+    "directory": "packages/llrt-analyzer"
+  },
+  "bugs": {
+    "url": "https://github.com/DavidWells/smart-ci/issues"
+  },
+  "homepage": "https://github.com/DavidWells/smart-ci/tree/master/packages/llrt-analyzer#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "ISC",
+  "dependencies": {
+    "@davidwells/smart-log": "^2.0.4",
+    "esbuild": "^0.27.0",
+    "precinct": "^8.3.1"
+  },
+  "devDependencies": {
+    "uvu": "^0.5.6"
+  }
+}

package/src/binary-manager.js

@@ -0,0 +1,152 @@
+// @ts-check
+'use strict'
+/**
+ * LLRT binary manager (bead sci-xwk.14).
+ *
+ * Ensure the pinned LLRT binary for the host platform/arch (+ sdk bundle
+ * variant) is downloaded, unzipped, and cached under ~/.smart-ci/llrt/<ver>/ so
+ * Tier-2/3 runs are reproducible. Returns the executable path. Skips-with-a-
+ * clear-error when offline and not cached.
+ */
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const https = require('https')
+const crypto = require('crypto')
+const { spawnSync } = require('child_process')
+const { ORG_PINNED_LLRT_VERSION, loadBinaryChecksums } = require('./knowledge-base')
+
+const CACHE_ROOT = path.join(os.homedir(), '.smart-ci', 'llrt')
+
+/** @returns {{ platform: string, arch: string }} */
+function hostTarget() {
+  const platform = { darwin: 'darwin', linux: 'linux', win32: 'windows' }[process.platform]
+  const arch = { arm64: 'arm64', x64: 'x64' }[process.arch]
+  if (!platform || !arch) throw new Error(`llrt-analyzer: unsupported host ${process.platform}/${process.arch}`)
+  return { platform, arch }
+}
+
+/**
+ * @param {{ version?: string, sdk?: 'no-sdk'|'std-sdk'|'full-sdk' }} [opts]
+ * @returns {Promise<string>} absolute path to the `llrt` executable
+ */
+async function getLlrtBinary(opts = {}) {
+  const version = opts.version || ORG_PINNED_LLRT_VERSION
+  const sdk = opts.sdk || 'full-sdk'
+  const { platform, arch } = hostTarget()
+  const suffix = sdk === 'std-sdk' ? '' : sdk === 'no-sdk' ? '-no-sdk' : '-full-sdk'
+  const asset = `llrt-${platform}-${arch}${suffix}.zip`
+  const dir = path.join(CACHE_ROOT, version, `${platform}-${arch}-${sdk}`)
+  const bin = path.join(dir, 'llrt')
+
+  if (fs.existsSync(bin)) return bin
+
+  const url = `https://github.com/awslabs/llrt/releases/download/v${version}/${asset}`
+  fs.mkdirSync(dir, { recursive: true })
+  const zip = path.join(dir, asset)
+  try {
+    await download(url, zip)
+  } catch (err) {
+    throw new Error(
+      `llrt-analyzer: could not fetch the LLRT binary (${asset} @ v${version}). ` +
+        `${err.message}. Tier-2/3 need it; run online once to cache, or pin a released version.`,
+    )
+  }
+  const unzip = spawnSync('unzip', ['-o', zip, '-d', dir], { encoding: 'utf8' })
+  if (unzip.status !== 0) throw new Error(`llrt-analyzer: unzip failed for ${asset}: ${unzip.stderr || unzip.stdout}`)
+  if (!fs.existsSync(bin)) {
+    // Some archives nest the binary; find it.
+    const found = findBinary(dir)
+    if (found && found !== bin) fs.renameSync(found, bin)
+  }
+  if (!fs.existsSync(bin)) throw new Error(`llrt-analyzer: llrt executable not found after unzip in ${dir}`)
+
+  // Supply-chain: we EXECUTE this binary, so verify it against the pinned hash.
+  // A mismatch aborts (and removes the file); an unlisted asset is allowed but
+  // logs its observed hash so a maintainer can pin it.
+  verifyChecksum(bin, asset, version)
+
+  fs.chmodSync(bin, 0o755)
+  try {
+    fs.unlinkSync(zip)
+  } catch (_) {
+    /* ignore */
+  }
+  return bin
+}
+
+/** sha256 a file. */
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')
+}
+
+/**
+ * Verify the extracted binary against data/llrt-binary-checksums.<version>.json.
+ * @param {string} bin @param {string} asset @param {string} version
+ */
+function verifyChecksum(bin, asset, version) {
+  const pinned = (loadBinaryChecksums(version).binaries || {})[asset]
+  const observed = sha256File(bin)
+  if (!pinned) {
+    process.stderr.write(
+      `llrt-analyzer: no pinned checksum for ${asset} @ v${version} — proceeding (TOFU). ` +
+        `Pin it in data/llrt-binary-checksums.${version}.json:\n  "${asset}": "${observed}"\n`,
+    )
+    return
+  }
+  if (observed !== pinned) {
+    try {
+      fs.unlinkSync(bin)
+    } catch (_) {
+      /* ignore */
+    }
+    throw new Error(
+      `llrt-analyzer: checksum MISMATCH for ${asset} @ v${version}.\n  expected ${pinned}\n  got      ${observed}\n` +
+        'Refusing to run a binary that does not match the pinned hash (possible tampering/corruption).',
+    )
+  }
+}
+
+/** Is a usable llrt binary already cached (no network)? */
+function isCached(opts = {}) {
+  const version = opts.version || ORG_PINNED_LLRT_VERSION
+  const sdk = opts.sdk || 'full-sdk'
+  const { platform, arch } = hostTarget()
+  return fs.existsSync(path.join(CACHE_ROOT, version, `${platform}-${arch}-${sdk}`, 'llrt'))
+}
+
+function findBinary(dir) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name)
+    if (e.isFile() && (e.name === 'llrt' || e.name === 'bootstrap')) return full
+    if (e.isDirectory()) {
+      const nested = findBinary(full)
+      if (nested) return nested
+    }
+  }
+  return null
+}
+
+function download(url, dest, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) return reject(new Error('too many redirects'))
+    https
+      .get(url, { headers: { 'user-agent': 'llrt-analyzer' } }, (res) => {
+        if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume()
+          return resolve(download(res.headers.location, dest, redirects + 1))
+        }
+        if (res.statusCode !== 200) {
+          res.resume()
+          return reject(new Error(`GET ${url} -> ${res.statusCode}`))
+        }
+        const out = fs.createWriteStream(dest)
+        res.pipe(out)
+        out.on('finish', () => out.close(() => resolve(dest)))
+        out.on('error', reject)
+      })
+      .on('error', reject)
+  })
+}
+
+module.exports = { getLlrtBinary, isCached, hostTarget, sha256File, download, CACHE_ROOT }

package/src/build-for-llrt.js

@@ -0,0 +1,137 @@
+// @ts-check
+'use strict'
+/**
+ * buildForLlrt (bead sci-xwk.15) — esbuild-bundle a handler into an LLRT-ready
+ * .mjs VERIFY artifact: es2023 / esm, TS transpiled, and every @aws-sdk/@smithy
+ * import aliased to the recorder shim (sci-xwk.16) so runs have no side effects
+ * and capture SDK calls uniformly under Node and LLRT. A generated entry inlines
+ * the fetch recorder + a run harness that invokes the handler with a corpus
+ * event (read from process.env.VERIFY_EVENT_FILE) and prints a JSON result.
+ */
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const crypto = require('crypto')
+
+const RECORDER = path.join(__dirname, 'runtime', 'aws-recorder.cjs')
+const RESULT_MARKER = '__LLRT_VERIFY_RESULT__'
+
+/**
+ * @param {{ entryPoint: string, outDir?: string, handlerExport?: string }} input
+ * @returns {Promise<{ outFile: string, resultMarker: string, warnings: string[], errors: string[] }>}
+ */
+async function buildForLlrt(input) {
+  // eslint-disable-next-line global-require
+  const esbuild = require('esbuild')
+  const outDir = input.outDir || fs.mkdtempSync(path.join(os.tmpdir(), 'llrt-verify-'))
+  fs.mkdirSync(outDir, { recursive: true })
+  const entryAbs = path.resolve(input.entryPoint)
+  const genEntry = path.join(outDir, '__verify_entry.mjs')
+  fs.writeFileSync(genEntry, verifyEntrySource(entryAbs, input.handlerExport))
+
+  const outFile = path.join(outDir, 'verify.mjs')
+  const result = await esbuild.build({
+    entryPoints: [genEntry],
+    bundle: true,
+    format: 'esm',
+    target: 'es2023',
+    platform: 'node', // keep node: builtins external — LLRT provides its (partial) versions
+    outfile: outFile,
+    logLevel: 'silent',
+    metafile: false,
+    plugins: [awsRecorderAlias()],
+  })
+  // LLRT resolves `node:querystring` but not bare `querystring`. esbuild
+  // auto-externalizes builtins without the prefix, so rewrite them (only in
+  // import/require positions, never in data string literals).
+  fs.writeFileSync(outFile, nodePrefixBundle(fs.readFileSync(outFile, 'utf8')))
+  return {
+    outFile,
+    resultMarker: RESULT_MARKER,
+    warnings: (result.warnings || []).map((w) => w.text),
+    errors: (result.errors || []).map((e) => e.text),
+  }
+}
+
+/** Rewrite bare node-builtin specifiers to `node:`-prefixed ones, ONLY in
+ * import/require positions (from"x" / import"x" / require("x") / __require("x")),
+ * never in data string literals. */
+function nodePrefixBundle(code) {
+  const nodeModule = require('module')
+  const isBuiltin =
+    typeof nodeModule.isBuiltin === 'function'
+      ? (n) => nodeModule.isBuiltin(n)
+      : ((set) => (n) => set.has(String(n).replace(/^node:/, '')))(new Set(nodeModule.builtinModules))
+  const re = /\b(from|import|require|__require\d*|__toESM\s*\(\s*require)\s*\(?\s*(["'])([a-z][a-z0-9_/]*)\2/g
+  return code.replace(re, (match, kw, quote, name) => {
+    if (!isBuiltin(name) || name.startsWith('node:')) return match
+    return match.replace(`${quote}${name}${quote}`, `${quote}node:${name}${quote}`)
+  })
+}
+
+/** esbuild plugin: alias every AWS SDK / smithy import to the recorder shim. */
+function awsRecorderAlias() {
+  return {
+    name: 'aws-recorder-alias',
+    setup(build) {
+      build.onResolve({ filter: /^@aws-sdk\/|^@smithy\/|^@aws-crypto\// }, () => ({ path: RECORDER }))
+    },
+  }
+}
+
+/** The generated verify entry (ESM) — runs identically under Node and LLRT. */
+function verifyEntrySource(entryAbs, handlerExport) {
+  const pick = handlerExport
+    ? `__mod[${JSON.stringify(handlerExport)}]`
+    : '__mod.handler || (__mod.default && (__mod.default.handler || __mod.default)) || __mod.default'
+  return `// generated by llrt-analyzer buildForLlrt — do not edit
+import * as __mod from ${JSON.stringify(entryAbs)}
+import __fs from 'node:fs'
+
+globalThis.__LLRT_CALLS__ = globalThis.__LLRT_CALLS__ || []
+const __origFetch = globalThis.fetch
+globalThis.fetch = async (input, init) => {
+  try {
+    const url = typeof input === 'string' ? input : (input && input.url) || ''
+    const method = (init && init.method) || (input && input.method) || 'GET'
+    let body
+    if (init && init.body != null) body = typeof init.body === 'string' ? init.body : '[stream]'
+    globalThis.__LLRT_CALLS__.push({ kind: 'fetch', method: String(method).toUpperCase(), url, body })
+  } catch (e) { /* ignore */ }
+  return new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } })
+}
+
+const RESULT = ${JSON.stringify(RESULT_MARKER)}
+
+// Cold-start measurement: when LLRT_INIT_ONLY is set, all imports above have
+// already executed (that IS the init/cold-start cost) — print + exit before
+// invoking the handler so the caller times pure init under Node vs LLRT.
+if (typeof process !== 'undefined' && process.env && process.env.LLRT_INIT_ONLY) {
+  console.log(RESULT + JSON.stringify({ ok: true, initOnly: true, calls: [] }))
+} else {
+  __run()
+}
+
+async function __run() {
+  const handler = ${pick}
+  if (typeof handler !== 'function') {
+    console.log(RESULT + JSON.stringify({ ok: false, error: 'no handler export found', calls: [] }))
+    return
+  }
+  let event = {}
+  try {
+    const p = typeof process !== 'undefined' && process.env && process.env.VERIFY_EVENT_FILE
+    if (p) event = JSON.parse(__fs.readFileSync(p, 'utf8'))
+  } catch (e) { /* default {} */ }
+  const ctx = { awsRequestId: 'llrt-verify', functionName: 'verify', getRemainingTimeInMillis: () => 30000, callbackWaitsForEmptyEventLoop: false }
+  try {
+    const response = await handler(event, ctx)
+    console.log(RESULT + JSON.stringify({ ok: true, response, calls: globalThis.__LLRT_CALLS__ }))
+  } catch (err) {
+    console.log(RESULT + JSON.stringify({ ok: false, error: String((err && err.message) || err), stack: String((err && err.stack) || ''), calls: globalThis.__LLRT_CALLS__ }))
+  }
+}
+`
+}
+
+module.exports = { buildForLlrt, RESULT_MARKER }