@tetsuo-ai/agenc 0.6.0 → 0.7.2

package/lib/generated-wrapper.mjs

@@ -0,0 +1,197 @@
+// Byte-canonical standalone-installer wrapper contract shared by the runtime
+// updater and both embedded installers. Parsing is deliberately full-file:
+// marker substrings must never grant ownership of a user-authored executable.
+
+import { isAbsolute } from "node:path";
+
+export const GENERATED_WRAPPER_MAX_BYTES = 64 * 1024;
+const POSIX_WRAPPER_SIGNATURE = "Generated by AgenC install.sh";
+const CMD_WRAPPER_SIGNATURE = "Generated by AgenC install.ps1";
+const WRAPPER_METADATA_PREFIX = "AgenC wrapper metadata v1:";
+
+function validateValues(kind, values) {
+  if (!values || typeof values !== "object") {
+    throw new TypeError("wrapper values must be an object");
+  }
+  for (const label of ["nodeBin", "runtimeBin", "agencHome"]) {
+    const value = values[label];
+    if (typeof value !== "string") throw new TypeError(`wrapper ${label} must be a string`);
+    if (value.includes("\0")) throw new Error(`wrapper ${label} contains NUL`);
+    if (kind === "cmd" && /["\r\n]/u.test(value)) {
+      throw new Error(`Windows wrapper ${label} contains an unsupported character`);
+    }
+  }
+  if (!isAbsolute(values.agencHome)) {
+    throw new Error("wrapper AGENC_HOME must be an absolute path");
+  }
+}
+
+function metadataFor(values) {
+  return Buffer.from(JSON.stringify({
+    nodeBin: values.nodeBin,
+    runtimeBin: values.runtimeBin,
+    agencHome: values.agencHome,
+  }), "utf8").toString("base64url");
+}
+
+function renderLegacyOomPosixWrapper({ nodeBin, runtimeBin, agencHome }) {
+  return [
+    "#!/bin/sh",
+    `# ${POSIX_WRAPPER_SIGNATURE} — rewritten on every install/upgrade.`,
+    `export AGENC_HOME="\${AGENC_HOME:-${agencHome}}"`,
+    "# OOM self-diagnosis: have V8 write a heap snapshot from inside the GC when",
+    "# the heap nears its limit (reliable even in the end-stage GC stall where JS",
+    "# timers starve), into $AGENC_HOME/oom-snapshots. The runtime prunes old",
+    "# captures and points at fresh ones on the next startup. User-provided",
+    "# NODE_OPTIONS win: ours are prepended, and we skip entirely when the user",
+    "# already tunes heap snapshots.",
+    'case " ${NODE_OPTIONS:-} " in',
+    "  *heapsnapshot-near-heap-limit*) : ;;",
+    "  *)",
+    '    mkdir -p "${AGENC_HOME}/oom-snapshots" 2>/dev/null || :',
+    '    NODE_OPTIONS="--heapsnapshot-near-heap-limit=1 --diagnostic-dir=${AGENC_HOME}/oom-snapshots ${NODE_OPTIONS:-}"',
+    "    export NODE_OPTIONS",
+    "    ;;",
+    "esac",
+    `exec "${nodeBin}" "${runtimeBin}" "$@"`,
+    "",
+  ].join("\n");
+}
+
+export function renderGeneratedWrapperContent({ kind, nodeBin, runtimeBin, agencHome }) {
+  if (kind !== "posix" && kind !== "cmd") {
+    throw new TypeError(`unsupported wrapper kind: ${String(kind)}`);
+  }
+  const values = { nodeBin, runtimeBin, agencHome };
+  validateValues(kind, values);
+  const metadata = metadataFor(values);
+  if (kind === "cmd") {
+    const batch = (value) => value.replaceAll("%", "%%");
+    return [
+      "@echo off",
+      "setlocal DisableDelayedExpansion",
+      `rem ${CMD_WRAPPER_SIGNATURE} - rewritten on every install/upgrade.`,
+      `rem ${WRAPPER_METADATA_PREFIX} ${metadata}`,
+      `if not defined AGENC_HOME set "AGENC_HOME=${batch(agencHome)}"`,
+      `"${batch(nodeBin)}" "${batch(runtimeBin)}" %*`,
+      "",
+    ].join("\r\n");
+  }
+  const quote = (value) => `'${value.replaceAll("'", `'"'"'`)}'`;
+  return [
+    "#!/bin/sh",
+    `# ${POSIX_WRAPPER_SIGNATURE} — rewritten on every install/upgrade.`,
+    `# ${WRAPPER_METADATA_PREFIX} ${metadata}`,
+    'if [ -z "${AGENC_HOME:-}" ]; then',
+    `  export AGENC_HOME=${quote(agencHome)}`,
+    "fi",
+    "# Capture one V8 near-heap-limit snapshot unless the operator already configured it.",
+    'case " ${NODE_OPTIONS:-} " in',
+    "  *heapsnapshot-near-heap-limit*)",
+    `    exec ${quote(nodeBin)} ${quote(runtimeBin)} "$@"`,
+    "    ;;",
+    "  *)",
+    '    mkdir -p "${AGENC_HOME}/oom-snapshots" 2>/dev/null || :',
+    `    exec ${quote(nodeBin)} --heapsnapshot-near-heap-limit=1 ` +
+      '--diagnostic-dir="${AGENC_HOME}/oom-snapshots" ' +
+      `${quote(runtimeBin)} "$@"`,
+    "    ;;",
+    "esac",
+    "",
+  ].join("\n");
+}
+
+function decodeCanonicalMetadata(encoded) {
+  try {
+    const bytes = Buffer.from(encoded, "base64url");
+    if (bytes.toString("base64url") !== encoded) return undefined;
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const value = JSON.parse(decoded);
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+    if (
+      Object.keys(value).length !== 3 ||
+      typeof value.nodeBin !== "string" ||
+      typeof value.runtimeBin !== "string" ||
+      typeof value.agencHome !== "string"
+    ) return undefined;
+    return {
+      nodeBin: value.nodeBin,
+      runtimeBin: value.runtimeBin,
+      agencHome: value.agencHome,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function parseModern(path, content) {
+  const marker = content.match(
+    /^(#|rem) AgenC wrapper metadata v1: ([A-Za-z0-9_-]+)\r?$/mu,
+  );
+  if (marker === null) return undefined;
+  const kind = marker[1] === "rem" ? "cmd" : "posix";
+  const values = decodeCanonicalMetadata(marker[2]);
+  if (values === undefined) return undefined;
+  try {
+    const wrapper = { kind, path, ...values };
+    return renderGeneratedWrapperContent(wrapper) === content ? wrapper : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function parseLegacy(path, content) {
+  const posix = content.match(
+    /^#!\/bin\/sh\n# Generated by AgenC install\.sh — rewritten on every install\/upgrade\.\nexport AGENC_HOME="\$\{AGENC_HOME:-([^}"\n]+)\}"\nexec "([^"\n]+)" "([^"\n]+)" "\$@"\n$/u,
+  );
+  if (posix !== null) {
+    const values = { agencHome: posix[1], nodeBin: posix[2], runtimeBin: posix[3] };
+    try {
+      validateValues("posix", values);
+      return { kind: "posix", path, ...values };
+    } catch {
+      return undefined;
+    }
+  }
+  // 0.6.2 development main briefly emitted this exact full-file wrapper before
+  // activation ownership became canonical. Accepting only a byte-for-byte
+  // reconstruction preserves upgrades from that surface without turning the
+  // historical marker into a general ownership oracle.
+  const oomPosix = content.match(
+    /^#!\/bin\/sh\n# Generated by AgenC install\.sh — rewritten on every install\/upgrade\.\nexport AGENC_HOME="\$\{AGENC_HOME:-([^}"\n]+)\}"\n[\s\S]*\nexec "([^"\n]+)" "([^"\n]+)" "\$@"\n$/u,
+  );
+  if (oomPosix !== null) {
+    const values = {
+      agencHome: oomPosix[1],
+      nodeBin: oomPosix[2],
+      runtimeBin: oomPosix[3],
+    };
+    try {
+      validateValues("posix", values);
+      if (renderLegacyOomPosixWrapper(values) === content) {
+        return { kind: "posix", path, ...values };
+      }
+    } catch {
+      return undefined;
+    }
+  }
+  const cmd = content.match(
+    /^@echo off(\r?\n)rem Generated by AgenC install\.ps1 - rewritten on every install\/upgrade\.\1if not defined AGENC_HOME set "AGENC_HOME=([^"\r\n]+)"\1"([^"\r\n]+)" "([^"\r\n]+)" %\*\1$/u,
+  );
+  if (cmd === null) return undefined;
+  const values = { agencHome: cmd[2], nodeBin: cmd[3], runtimeBin: cmd[4] };
+  try {
+    validateValues("cmd", values);
+    return { kind: "cmd", path, ...values };
+  } catch {
+    return undefined;
+  }
+}
+
+export function parseGeneratedWrapperContent(path, content) {
+  if (
+    typeof path !== "string" || !isAbsolute(path) ||
+    typeof content !== "string" || Buffer.byteLength(content, "utf8") > GENERATED_WRAPPER_MAX_BYTES
+  ) return null;
+  return parseModern(path, content) ?? parseLegacy(path, content) ?? null;
+}

package/lib/runtime-archive.mjs

@@ -0,0 +1,299 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { posix } from "node:path";
+import { TextDecoder } from "node:util";
+import { gunzipSync } from "node:zlib";
+
+const BLOCK_SIZE = 512;
+const MAX_UNCOMPRESSED_BYTES = 512 * 1024 * 1024;
+const MAX_ENTRIES = 200_000;
+const MAX_SYMLINK_EXPANSIONS = 64;
+const decoder = new TextDecoder("utf-8", { fatal: true });
+
+function field(block, start, length) {
+  const bytes = block.subarray(start, start + length);
+  const end = bytes.indexOf(0);
+  return decoder.decode(end === -1 ? bytes : bytes.subarray(0, end));
+}
+
+function octal(block, start, length, label) {
+  const raw = field(block, start, length).trim();
+  if (!/^[0-7]+$/.test(raw)) throw new Error(`invalid tar ${label}`);
+  const value = Number.parseInt(raw, 8);
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`invalid tar ${label}`);
+  return value;
+}
+
+function validateChecksum(block) {
+  const expected = octal(block, 148, 8, "checksum");
+  let actual = 0;
+  for (let index = 0; index < BLOCK_SIZE; index += 1) {
+    actual += index >= 148 && index < 156 ? 0x20 : block[index];
+  }
+  if (actual !== expected) throw new Error("invalid tar header checksum");
+}
+
+function parsePax(data) {
+  const values = {};
+  const seenKeys = new Set();
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) throw new Error("invalid PAX record length");
+    const lengthText = data.subarray(offset, space).toString("ascii");
+    if (!/^[1-9][0-9]*$/.test(lengthText)) throw new Error("invalid PAX record length");
+    const length = Number(lengthText);
+    const end = offset + length;
+    if (!Number.isSafeInteger(length) || end > data.length || data[end - 1] !== 0x0a) {
+      throw new Error("invalid PAX record boundary");
+    }
+    const record = decoder.decode(data.subarray(space + 1, end - 1));
+    const equals = record.indexOf("=");
+    if (equals <= 0) throw new Error("invalid PAX record");
+    const key = record.slice(0, equals);
+    const value = record.slice(equals + 1);
+    if (seenKeys.has(key)) throw new Error(`duplicate PAX key: ${key}`);
+    seenKeys.add(key);
+    if (key === "path" || key === "linkpath") values[key] = value;
+    else if (key === "size") {
+      if (!/^(0|[1-9][0-9]*)$/.test(value)) throw new Error("invalid PAX size");
+      const size = Number(value);
+      if (!Number.isSafeInteger(size) || size > MAX_UNCOMPRESSED_BYTES) {
+        throw new Error("invalid PAX size");
+      }
+      values.size = size;
+    } else if (["mtime", "atime", "ctime"].includes(key)) {
+      if (!/^(0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(value)) {
+        throw new Error(`invalid PAX ${key}`);
+      }
+    } else throw new Error(`unsupported PAX key: ${key}`);
+    offset = end;
+  }
+  return values;
+}
+
+function unsafePortableSegment(part, platform) {
+  if (platform !== "win" && platform !== "darwin") return false;
+  if (/[. ]$/.test(part)) return true;
+  return platform === "win" && (
+    part.includes(":") ||
+    /^(con|prn|aux|nul|com[1-9\u00b9\u00b2\u00b3]|lpt[1-9\u00b9\u00b2\u00b3])(?:\.|$)/iu.test(part)
+  );
+}
+
+function validateMemberPath(path, platform, collisionPaths) {
+  if (
+    path.length === 0 ||
+    /[\\\x00-\x1f\x7f]/.test(path) ||
+    path.startsWith("/") ||
+    /^[A-Za-z]:/.test(path)
+  ) {
+    throw new Error(`unsafe runtime archive path: ${path || "(empty)"}`);
+  }
+  const trimmed = path.endsWith("/") ? path.slice(0, -1) : path;
+  const parts = trimmed.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error(`unsafe runtime archive path: ${path}`);
+  }
+  if (trimmed !== "node_modules" && !trimmed.startsWith("node_modules/")) {
+    throw new Error(`runtime archive member is outside node_modules: ${path}`);
+  }
+  if (platform === "win" || platform === "darwin") {
+    let prefix = "";
+    for (const part of parts) {
+      if (unsafePortableSegment(part, platform)) {
+        throw new Error(`unsafe runtime archive path for ${platform}: ${path}`);
+      }
+      prefix = prefix ? `${prefix}/${part}` : part;
+      const collisionKey = prefix.normalize("NFC").toLowerCase();
+      const prior = collisionPaths.get(collisionKey);
+      if (prior !== undefined && prior !== prefix) {
+        throw new Error(`runtime archive has a case/Unicode path collision: ${prior} and ${prefix}`);
+      }
+      collisionPaths.set(collisionKey, prefix);
+    }
+  }
+  return trimmed;
+}
+
+function validateLink(memberPath, linkPath, platform) {
+  if (
+    linkPath.length === 0 ||
+    /[\\\x00-\x1f\x7f]/.test(linkPath) ||
+    linkPath.startsWith("/") ||
+    /^[A-Za-z]:/.test(linkPath)
+  ) {
+    throw new Error(`unsafe runtime archive link target: ${linkPath || "(empty)"}`);
+  }
+  if (
+    (platform === "win" || platform === "darwin") &&
+    linkPath.split("/").some((part) =>
+      part !== "." && part !== ".." && unsafePortableSegment(part, platform))
+  ) {
+    throw new Error(`unsafe runtime archive link target for ${platform}: ${linkPath}`);
+  }
+  const resolved = posix.normalize(posix.join(posix.dirname(memberPath), linkPath));
+  if (resolved !== "node_modules" && !resolved.startsWith("node_modules/")) {
+    throw new Error(`runtime archive link escapes node_modules: ${memberPath} -> ${linkPath}`);
+  }
+}
+
+function resolveArchiveGraphPath(components, links) {
+  const pending = [...components];
+  const resolved = [];
+  let expansions = 0;
+  let steps = 0;
+  while (pending.length > 0) {
+    if (++steps > MAX_ENTRIES + MAX_SYMLINK_EXPANSIONS) {
+      throw new Error("runtime archive symlink resolution is too complex");
+    }
+    const part = pending.shift() ?? "";
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (resolved.length === 0) {
+        throw new Error("runtime archive symlink graph escapes the extraction root");
+      }
+      resolved.pop();
+      continue;
+    }
+    resolved.push(part);
+    const candidate = resolved.join("/");
+    const target = links.get(candidate);
+    if (target === undefined) continue;
+    expansions += 1;
+    if (expansions > MAX_SYMLINK_EXPANSIONS) {
+      throw new Error("runtime archive symlink graph contains a cycle or excessive depth");
+    }
+    resolved.pop();
+    pending.unshift(...target.split("/"));
+  }
+  return resolved.join("/");
+}
+
+function assertGraphResultWithinNodeModules(path) {
+  if (path !== "node_modules" && !path.startsWith("node_modules/")) {
+    throw new Error(`runtime archive symlink graph escapes node_modules: ${path || "(root)"}`);
+  }
+}
+
+function validateSymlinkGraph(members, links) {
+  for (const member of members) {
+    if (member.type === "2") {
+      const parent = posix.dirname(member.path);
+      if (parent !== ".") {
+        assertGraphResultWithinNodeModules(
+          resolveArchiveGraphPath(parent.split("/"), links),
+        );
+      }
+      const target = links.get(member.path);
+      if (target === undefined) throw new Error(`missing runtime archive link target: ${member.path}`);
+      assertGraphResultWithinNodeModules(resolveArchiveGraphPath([
+        ...(parent === "." ? [] : parent.split("/")),
+        ...target.split("/"),
+      ], links));
+    } else {
+      assertGraphResultWithinNodeModules(
+        resolveArchiveGraphPath(member.path.split("/"), links),
+      );
+    }
+  }
+}
+
+function inspectRuntimeArchive(
+  path,
+  platform = process.platform === "win32" ? "win" : process.platform,
+  includeContentInventory = false,
+) {
+  const archive = gunzipSync(readFileSync(path), {
+    maxOutputLength: MAX_UNCOMPRESSED_BYTES,
+  });
+  let offset = 0;
+  let entries = 0;
+  let pendingPax;
+  const seen = new Set();
+  const members = [];
+  const links = new Map();
+  const collisionPaths = new Map();
+  let pendingPaxStart;
+  while (offset + BLOCK_SIZE <= archive.length) {
+    const recordStart = pendingPaxStart ?? offset;
+    const header = archive.subarray(offset, offset + BLOCK_SIZE);
+    if (header.every((byte) => byte === 0)) break;
+    validateChecksum(header);
+    const size = octal(header, 124, 12, "entry size");
+    const dataStart = offset + BLOCK_SIZE;
+    const dataEnd = dataStart + size;
+    if (dataEnd > archive.length) throw new Error("truncated tar entry");
+    const type = String.fromCharCode(header[156] || 0x30);
+    const prefix = field(header, 345, 155);
+    const headerPath = [prefix, field(header, 0, 100)].filter(Boolean).join("/");
+    const headerLink = field(header, 157, 100);
+    if (type === "x") {
+      if (pendingPax !== undefined) throw new Error("stacked PAX headers are not allowed");
+      pendingPax = parsePax(archive.subarray(dataStart, dataEnd));
+      pendingPaxStart = offset;
+    } else {
+      if (pendingPax?.size !== undefined && pendingPax.size !== size) {
+        throw new Error("PAX size does not match tar header size");
+      }
+      if (!["0", "5", "2"].includes(type)) {
+        throw new Error(`unsupported runtime archive member type: ${type}`);
+      }
+      const memberPath = validateMemberPath(
+        pendingPax?.path ?? headerPath,
+        platform,
+        collisionPaths,
+      );
+      if (seen.has(memberPath)) throw new Error(`duplicate runtime archive member: ${memberPath}`);
+      seen.add(memberPath);
+      if (type === "2") {
+        const linkPath = pendingPax?.linkpath ?? headerLink;
+        validateLink(memberPath, linkPath, platform);
+        links.set(memberPath, linkPath);
+      }
+      const member = { path: memberPath, type };
+      if (includeContentInventory) {
+        const recordEnd = dataStart + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+        member.bytes = size;
+        member.mode = octal(header, 100, 8, "entry mode");
+        member.contentSha256 = createHash("sha256")
+          .update(archive.subarray(dataStart, dataEnd))
+          .digest("hex");
+        member.recordSha256 = createHash("sha256")
+          .update(archive.subarray(recordStart, recordEnd))
+          .digest("hex");
+        if (type === "2") member.linkPath = pendingPax?.linkpath ?? headerLink;
+      }
+      members.push(member);
+      pendingPax = undefined;
+      pendingPaxStart = undefined;
+      entries += 1;
+      if (entries > MAX_ENTRIES) throw new Error("runtime archive has too many entries");
+    }
+    offset = dataStart + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE;
+  }
+  if (pendingPax !== undefined) throw new Error("orphaned PAX header");
+  if (entries === 0 || !seen.has("node_modules")) {
+    throw new Error("runtime archive is empty or missing node_modules");
+  }
+  validateSymlinkGraph(members, links);
+  return {
+    entries,
+    uncompressedBytes: archive.length,
+    ...(includeContentInventory ? { members } : {}),
+  };
+}
+
+export function validateRuntimeArchive(
+  path,
+  platform = process.platform === "win32" ? "win" : process.platform,
+) {
+  return inspectRuntimeArchive(path, platform, false);
+}
+
+export function runtimeArchiveContentInventory(
+  path,
+  platform = process.platform === "win32" ? "win" : process.platform,
+) {
+  return inspectRuntimeArchive(path, platform, true);
+}

package/lib/runtime-compatibility.mjs

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { basename } from "node:path";
+
+const DOTTED_VERSION = /^\d+\.\d+(?:\.\d+)?$/;
+
+export function compareDottedVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < Math.max(leftParts.length, rightParts.length); index += 1) {
+    const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (difference !== 0) return Math.sign(difference);
+  }
+  return 0;
+}
+
+function maximumSymbolVersion(path, namespace) {
+  const bytes = readFileSync(path).toString("latin1");
+  const pattern = new RegExp(`\\b${namespace}_(\\d+\\.\\d+(?:\\.\\d+)?)\\b`, "g");
+  let maximum;
+  for (const match of bytes.matchAll(pattern)) {
+    if (maximum === undefined || compareDottedVersions(match[1], maximum) > 0) {
+      maximum = match[1];
+    }
+  }
+  return maximum;
+}
+
+export function currentRuntimeCompatibility({
+  platform = process.platform,
+  arch = process.arch,
+  nodeMajor = Number(process.versions.node.split(".")[0]),
+  nodeModuleAbi = process.versions.modules,
+  report = process.report?.getReport(),
+} = {}) {
+  const base = { platform: platform === "win32" ? "win" : platform, arch, nodeMajor, nodeModuleAbi };
+  if (base.platform === "darwin") {
+    const result = spawnSync("/usr/bin/sw_vers", ["-productVersion"], {
+      encoding: "utf8",
+    });
+    return {
+      ...base,
+      ...(result.status === 0 ? { macosVersion: result.stdout.trim() } : {}),
+    };
+  }
+  if (base.platform !== "linux") return base;
+  const glibcVersion = report?.header?.glibcVersionRuntime;
+  const libstdcxx = report?.sharedObjects?.find(
+    (path) => basename(path).startsWith("libstdc++.so.6"),
+  );
+  if (typeof glibcVersion !== "string" || !DOTTED_VERSION.test(glibcVersion)) {
+    return { ...base, libcFamily: "unknown" };
+  }
+  if (typeof libstdcxx !== "string") {
+    return { ...base, libcFamily: "glibc", glibcVersion };
+  }
+  return {
+    ...base,
+    libcFamily: "glibc",
+    glibcVersion,
+    glibcxxVersion: maximumSymbolVersion(libstdcxx, "GLIBCXX"),
+    cxxAbiVersion: maximumSymbolVersion(libstdcxx, "CXXABI"),
+  };
+}
+
+function requireDotted(value, label) {
+  if (typeof value !== "string" || !DOTTED_VERSION.test(value)) {
+    throw new Error(`agenc: runtime artifact has invalid ${label}`);
+  }
+  return value;
+}
+
+export function assertArtifactCompatible(artifact, runtime) {
+  if (artifact.nodeMajor !== runtime.nodeMajor) {
+    throw new Error(
+      `agenc: runtime artifact requires Node ${artifact.nodeMajor}.x; current Node is ${runtime.nodeMajor}.x`,
+    );
+  }
+  if (artifact.nodeModuleAbi !== runtime.nodeModuleAbi) {
+    throw new Error(
+      `agenc: runtime artifact requires native ABI ${artifact.nodeModuleAbi}; current ABI is ${runtime.nodeModuleAbi}`,
+    );
+  }
+  if (runtime.platform === "darwin") {
+    const minimum = requireDotted(
+      artifact.minimumMacosVersion,
+      "minimum macOS version",
+    );
+    if (
+      typeof runtime.macosVersion !== "string" ||
+      !DOTTED_VERSION.test(runtime.macosVersion)
+    ) {
+      throw new Error("agenc: could not determine host macOS compatibility");
+    }
+    if (compareDottedVersions(runtime.macosVersion, minimum) < 0) {
+      throw new Error(
+        `agenc: runtime requires macOS ${minimum} or newer; host provides ${runtime.macosVersion}`,
+      );
+    }
+    return artifact;
+  }
+  if (runtime.platform !== "linux") return artifact;
+  if (artifact.libcFamily !== "glibc") {
+    throw new Error("agenc: Linux runtime artifact does not declare the required glibc family");
+  }
+  if (runtime.libcFamily !== "glibc") {
+    throw new Error("agenc: Linux runtime requires glibc; musl/unknown libc is unsupported");
+  }
+  const requirements = [
+    [requireDotted(artifact.minimumGlibcVersion, "minimum glibc version"), runtime.glibcVersion, "glibc"],
+    [requireDotted(artifact.minimumGlibcxxVersion, "minimum GLIBCXX version"), runtime.glibcxxVersion, "GLIBCXX"],
+    [requireDotted(artifact.minimumCxxAbiVersion, "minimum CXXABI version"), runtime.cxxAbiVersion, "CXXABI"],
+  ];
+  for (const [minimum, current, label] of requirements) {
+    if (typeof current !== "string" || !DOTTED_VERSION.test(current)) {
+      throw new Error(`agenc: could not determine host ${label} compatibility`);
+    }
+    if (compareDottedVersions(current, minimum) < 0) {
+      throw new Error(
+        `agenc: Linux runtime requires ${label} ${minimum} or newer; host provides ${current}`,
+      );
+    }
+  }
+  return artifact;
+}
+
+export function runtimeArtifactKey(artifact) {
+  const platform = artifact?.platform;
+  const arch = artifact?.arch;
+  const abi = artifact?.nodeModuleAbi;
+  if (!/^(linux|darwin|win)$/.test(platform ?? "")) {
+    throw new Error(`agenc: invalid runtime platform ${platform ?? "missing"}`);
+  }
+  if (!/^(x64|arm64)$/.test(arch ?? "") || !/^\d+$/.test(abi ?? "")) {
+    throw new Error("agenc: invalid runtime architecture or native module ABI");
+  }
+  const libc = platform === "linux"
+    ? artifact.libcFamily === "glibc" ? "glibc" : "unknown-libc"
+    : "native";
+  return `${platform}-${arch}-${libc}-node-abi-${abi}`;
+}