animader-cli 0.0.0-stage → 0.1.1

package/src/toolchain.mjs

@@ -0,0 +1,691 @@
+// The installed toolchain boundary (installed-toolchain plan, stage 2).
+//
+// One descriptor answers every "where does this artifact come from"
+// question the CLI has, in one of two modes:
+//
+//   contributor — this source workspace: sibling checkouts (env
+//     overridable), the prepared demo/vendor bundle and the pngine
+//     owner's pinned esbuild. Exactly what the demo has always used.
+//
+//   installed — an npm-installed package: every artifact resolves through
+//     Node module resolution from this package's dependency graph
+//     (animader, pngine, @mr_hugo/pacer, the pinned esbuild, the @pngine/*
+//     and @mr_hugo/pacer-* platform packages), verified against the release
+//     manifest assembled at pack time. Installed mode never reads demo/,
+//     a sibling checkout, a zig cache or zig-out, and never consults the
+//     contributor environment overrides.
+//
+// Mode detection is the manifest's presence: the release assembly writes
+// toolchain/manifest.json into the package before npm pack, and the source
+// tree never carries one. ANIMADER_TOOLCHAIN=contributor|installed forces
+// a mode for tests.
+//
+// Every missing or omitted artifact is a DemoError with an exit code and a
+// remedy naming exactly what to install — never a stack trace, never a
+// silent pass.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { DemoError } from '../lib/errors.mjs';
+import { VENDOR_FORMAT } from '../lib/vendor.mjs';
+import { defaultContentRoot, resolveRoots, verifyVendor } from '../toolchain/prepare.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const MANIFEST_RELATIVE_PATH = 'toolchain/manifest.json';
+export const TOOLCHAIN_MANIFEST_FORMAT = 'animader-toolchain/1';
+
+/** The npm package name of the pacer runtime. The producer key stays
+ *  `pacer` (manifest producers, versions, vendor layout); this is only
+ *  the published name the dependency graph resolves. */
+export const PACER_PACKAGE = '@mr_hugo/pacer';
+
+/** The platform packages, reusing pngine's own @pngine/* scheme and
+ *  mirroring it for pacer's native pack CLI (stage 3). */
+export const PNGINE_PLATFORM_PACKAGES = Object.freeze({
+  'darwin-arm64': '@pngine/darwin-arm64',
+  'darwin-x64': '@pngine/darwin-x64',
+  'linux-arm64': '@pngine/linux-arm64',
+  'linux-x64': '@pngine/linux-x64',
+  'openbsd-x64': '@pngine/openbsd-x64',
+  'win32-arm64': '@pngine/win32-arm64',
+  'win32-x64': '@pngine/win32-x64',
+});
+
+export const PACER_PLATFORM_PACKAGES = Object.freeze(
+  Object.fromEntries(
+    Object.entries(PNGINE_PLATFORM_PACKAGES).map(([platform]) => [platform, `${PACER_PACKAGE}-${platform}`]),
+  ),
+);
+
+function toolchainError(code, message, remedy, extra = {}) {
+  return new DemoError(code, message, { exitCode: 4, remedy, ...extra });
+}
+
+function missingRemedy(packageName, version, artifact) {
+  return `Install ${packageName}@${version} (or reinstall animader-cli so its dependency graph pulls it): the ${artifact} comes from that package.`;
+}
+
+/**
+ * Detect the toolchain mode: forced by ANIMADER_TOOLCHAIN, else installed
+ * exactly when the package carries its release manifest (the source tree
+ * never does).
+ *
+ * @param {{env?: object, pkgRoot?: string}} [options]
+ * @returns {Promise<'contributor' | 'installed'>}
+ */
+export async function detectToolchainMode({ env = process.env, pkgRoot = PKG_ROOT } = {}) {
+  const forced = env.ANIMADER_TOOLCHAIN;
+  if (forced !== undefined) {
+    if (forced !== 'contributor' && forced !== 'installed') {
+      throw toolchainError(
+        'bad_toolchain_mode',
+        `ANIMADER_TOOLCHAIN=${JSON.stringify(forced)} is not a mode`,
+        'Set ANIMADER_TOOLCHAIN to "contributor" or "installed", or unset it to detect from the package layout.',
+      );
+    }
+    return forced;
+  }
+  return (await probeManifest(pkgRoot)) !== null ? 'installed' : 'contributor';
+}
+
+/** The manifest's absolute path when the package carries one. */
+async function probeManifest(pkgRoot) {
+  const path = join(pkgRoot, MANIFEST_RELATIVE_PATH);
+  const info = await stat(path).catch(() => null);
+  return info !== null && info.isFile() ? path : null;
+}
+
+function sha256(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+function canonicalRows(rows) {
+  return rows
+    .map((row) => `${row.path}|${row.source ?? row.spec ?? ''}|${row.sha256}|${row.bytes}`)
+    .sort()
+    .join('\n');
+}
+
+/**
+ * Validate the release manifest's shape. Returns a normalized copy.
+ *
+ * @param {unknown} manifest
+ * @returns {{format: string, toolchainVersion: string, target: {os: string, arch: string},
+ *           producers: Object, runtime: Array, tools: Object, helpers: Object,
+ *           pngineCore: Object, digest: string}}
+ */
+export function validateToolchainManifest(manifest) {
+  const bad = (detail) => toolchainError(
+    'bad_toolchain_manifest',
+    `the toolchain manifest is not valid: ${detail}`,
+    'Reinstall animader-cli; the release assembly writes this manifest, and a broken one means a broken package.',
+  );
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) throw bad('not an object');
+  if (manifest.format !== TOOLCHAIN_MANIFEST_FORMAT) {
+    throw bad(`format ${JSON.stringify(manifest.format)} is not ${TOOLCHAIN_MANIFEST_FORMAT}`);
+  }
+  if (typeof manifest.toolchainVersion !== 'string' || manifest.toolchainVersion === '') throw bad('no toolchainVersion');
+  const target = manifest.target;
+  if (target === null || typeof target !== 'object' || typeof target.os !== 'string' || typeof target.arch !== 'string') {
+    throw bad('no target {os, arch}');
+  }
+  if (target.os !== process.platform || target.arch !== process.arch) {
+    throw toolchainError(
+      'toolchain_platform_mismatch',
+      `this toolchain was assembled for ${target.os}-${target.arch}, not ${process.platform}-${process.arch}`,
+      `Install an animader-cli platform build for ${process.platform}-${process.arch}; this package's native binaries cannot run here.`,
+    );
+  }
+  for (const key of ['producers', 'runtime', 'tools', 'helpers', 'pngineCore']) {
+    if (manifest[key] === null || typeof manifest[key] !== 'object') throw bad(`no ${key}`);
+  }
+  if (!Array.isArray(manifest.runtime) || manifest.runtime.length === 0) throw bad('no runtime rows');
+  for (const row of manifest.runtime) {
+    if (typeof row.path !== 'string' || typeof row.spec !== 'string' || !/^[0-9a-f]{64}$/.test(String(row.sha256 ?? '')) || !Number.isInteger(row.bytes)) {
+      throw bad(`runtime row ${JSON.stringify(row?.path)} is not a {path, spec, sha256, bytes} record`);
+    }
+    // A row may record a file inside its package (producer src modules
+    // the owner's exports map does not expose). It must name exactly
+    // that: a relative path that stays inside the package root.
+    if (row.file !== undefined
+      && (typeof row.file !== 'string' || row.file === '' || row.file.startsWith('/') || row.file.includes('\\') || row.file.split('/').includes('..'))) {
+      throw bad(`runtime row ${JSON.stringify(row?.path)} carries an invalid package file ${JSON.stringify(row.file)}`);
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.tools)) {
+    if (typeof entry?.package !== 'string' || typeof entry.file !== 'string') {
+      throw bad(`tool ${name} is not a {package, file} record`);
+    }
+  }
+  const digest = sha256(canonicalRows(manifest.runtime));
+  if (manifest.digest !== digest) {
+    throw bad('the runtime digest does not match its rows');
+  }
+  return { ...manifest, digest };
+}
+
+/**
+ * Resolve the toolchain for this run. One descriptor, both modes; see the
+ * module comment. Contributor mode wraps toolchain/prepare.mjs's roots.
+ *
+ * @param {{env?: object, pkgRoot?: string, contributorRoots?: object}} [options]
+ */
+export async function resolveToolchain({ env = process.env, pkgRoot = PKG_ROOT, contributorRoots } = {}) {
+  const mode = await detectToolchainMode({ env, pkgRoot });
+  if (mode === 'installed') {
+    return resolveInstalledToolchain({ env, pkgRoot });
+  }
+  return contributorToolchain({
+    env,
+    roots: contributorRoots,
+    vendorRoot: contributorRoots?.vendorRoot,
+  });
+}
+
+/**
+ * The contributor-workspace toolchain, constructed synchronously: sibling
+ * checkout roots (env overridable), the prepared demo/vendor bundle and
+ * the pngine owner's pinned esbuild. Path resolution never touches the
+ * filesystem here; each artifact is existence-checked when used.
+ *
+ * @param {{env?: object, roots?: object, vendorRoot?: string}} [options]
+ */
+export function contributorToolchain({ env = process.env, roots, vendorRoot } = {}) {
+  // A partial roots object (tests pass only pngineRoot or only a vendor
+  // root) merges over the resolved workspace defaults, so every root the
+  // descriptor needs is present.
+  const resolved = { ...resolveRoots({ env }), ...(roots ?? {}) };
+  const repoRoot = vendorRoot !== undefined && roots === undefined
+    ? defaultContentRoot()
+    : resolve(resolved.contentRoot ?? defaultContentRoot());
+  const root = vendorRoot ?? join(repoRoot, 'demo', 'vendor');
+  const identity = 'source workspace (contributor mode)';
+
+  const file = (relative) => join(root, relative);
+  const requireFile = async (relative) => {
+    const path = file(relative);
+    const info = await stat(path).catch(() => null);
+    if (info === null || !info.isFile() || info.size === 0) {
+      throw toolchainError(
+        'toolchain_artifact_missing',
+        `the prepared runtime is missing ${relative}`,
+        'Run the one-time prepare: node demo/prepare.mjs (the contributor toolchain reads demo/vendor).',
+      );
+    }
+    return path;
+  };
+
+  const pnginePackageRoot = join(resolved.pngineRoot, 'npm', 'pngine');
+  const pacerPackageRoot = join(resolved.pacerRoot, 'npm', 'pacer');
+  const cliPackage = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+
+  const descriptor = {
+    mode: 'contributor',
+    identity,
+    target: { os: process.platform, arch: process.arch },
+    manifest: null,
+    runtime: {
+      kind: 'dir',
+      root,
+      /** Sync path answer: the vendor layout joined, no fs probe. */
+      path: (relative) => file(relative),
+      async requireFile(relative) { return requireFile(relative); },
+      async files() {
+        const verified = await verifyVendor({ vendorRoot: root });
+        return verified.files.map((row) => ({ path: row.path, source: join(root, row.path) }));
+      },
+    },
+    pngine: {
+      cli: resolved.pngineCli,
+      viewer: file('pngine.mjs'),
+      core: join(pnginePackageRoot, 'dist', 'core.mjs'),
+      uniformTypeName: join(pnginePackageRoot, 'src', 'uniform-convert.js'),
+    },
+    pacer: {
+      cli: join(resolved.pacerRoot, 'zig-out', 'bin', 'pacer'),
+      index: file('pacer/index.js'),
+      route: file('pacer/route.js'),
+      rt: file('pacer/rt.js'),
+      pacerWasm: file('pacer/pacer.wasm'),
+      pacerRtWasm: file('pacer/pacer-rt.wasm'),
+    },
+    animader: {
+      wasm: file('animader/animader.wasm'),
+      piece: file('animader/piece.js'),
+    },
+    versions: {
+      animader: null,
+      pngine: null,
+      pacer: null,
+      esbuild: cliPackage.dependencies?.esbuild ?? null,
+    },
+    esbuild: {
+      /** Resolve the pinned esbuild. Contributor mode reads the pngine
+       *  owner's install (the plan's pinned owner) and refuses drift from
+       *  the version this CLI declares. */
+      require() {
+        const requireFromPngine = createRequire(join(pnginePackageRoot, 'package.json'));
+        let esbuild;
+        try {
+          esbuild = requireFromPngine('esbuild');
+        } catch (cause) {
+          throw toolchainError(
+            'bundle_tool_missing',
+            'the pinned owner esbuild could not be resolved from the pngine checkout',
+            'Build/install the pngine npm workspace as prepared; the contributor toolchain bundles with the owner esbuild.',
+            { cause },
+          );
+        }
+        const pinned = cliPackage.dependencies?.esbuild;
+        if (typeof esbuild.version === 'string' && pinned && esbuild.version !== pinned) {
+          throw toolchainError(
+            'bundle_tool_version_drift',
+            `the pngine checkout carries esbuild ${esbuild.version}, but this CLI pins ${pinned}`,
+            `Align them: update the CLI's esbuild pin or the pngine workspace install to ${pinned}.`,
+          );
+        }
+        return esbuild;
+      },
+    },
+    async verifyRuntime() {
+      const verified = await verifyVendor({ vendorRoot: root });
+      return {
+        format: verified.format,
+        files: verified.files,
+        digest: verified.digest,
+        provenance: {
+          format: verified.format,
+          producers: verified.producers,
+          files: verified.files,
+          digest: verified.digest,
+        },
+      };
+    },
+    async verifyTools() {
+      const rows = [];
+      for (const [name, path] of [['pngine CLI', resolved.pngineCli], ['pacer CLI', descriptor.pacer.cli]]) {
+        const info = await stat(path).catch(() => null);
+        if (info === null || !info.isFile()) {
+          throw toolchainError(
+            'toolchain_artifact_missing',
+            `the ${name} binary is missing at ${path}`,
+            name === 'pngine CLI'
+              ? 'Build pngine in its checkout (zig build) or point PNGINE at the binary; contributor mode never installs it.'
+              : "Build the pacer CLI in its checkout (zig build cli) or set ANIMADER_PACER to that checkout; contributor mode never installs it.",
+          );
+        }
+        rows.push({ name, path, bytes: info.size, sha256: sha256(readFileSync(path)) });
+      }
+      return { tools: rows };
+    },
+    async licenseText() {
+      return readFile(join(repoRoot, 'LICENSE'), 'utf8');
+    },
+    async producerVersion(name) {
+      const packageRoot = name === 'pngine' ? pnginePackageRoot : name === 'pacer' ? pacerPackageRoot : null;
+      if (packageRoot === null) return null;
+      let text = '{"version":null}';
+      try {
+        text = readFileSync(join(packageRoot, 'package.json'), 'utf8');
+      } catch {
+        // A missing producer package answers no version, not a crash.
+      }
+      return JSON.parse(text).version ?? null;
+    },
+  };
+  return descriptor;
+}
+
+async function resolveInstalledToolchain({ env, pkgRoot }) {
+  const manifestPath = await probeManifest(pkgRoot);
+  if (manifestPath === null) {
+    throw toolchainError(
+      'toolchain_manifest_missing',
+      'this package runs in installed mode but carries no toolchain manifest',
+      'Reinstall animader-cli from its packed tarball; the release assembly writes toolchain/manifest.json.',
+    );
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (cause) {
+    throw toolchainError(
+      'bad_toolchain_manifest',
+      `the toolchain manifest is not JSON: ${cause.message}`,
+      'Reinstall animader-cli; the release assembly writes this manifest.',
+      { cause },
+    );
+  }
+  manifest = validateToolchainManifest(manifest);
+
+  const requireFromPackage = createRequire(join(pkgRoot, 'package.json'));
+  const platform = `${manifest.target.os}-${manifest.target.arch}`;
+  const versions = {
+    animader: manifest.producers?.animader?.version ?? null,
+    pngine: manifest.producers?.pngine?.version ?? null,
+    pacer: manifest.producers?.pacer?.version ?? null,
+    esbuild: manifest.producers?.esbuild?.version ?? null,
+  };
+
+  /**
+   * Resolve one spec from the installed dependency graph. Plain-string
+   * exports go through require.resolve; browser/import-conditioned
+   * exports (pngine's viewer and core) are resolved by reading the
+   * package's own exports map — Node's require.resolve refuses the
+   * "import" condition, and the installed CLI must not depend on a
+   * bundler to find its artifacts. Any reshape of the owner's exports
+   * turns into the named missing-artifact failure instead of a guess.
+   */
+  function resolveSpec(spec, packageName, version, artifact) {
+    const missing = (cause) => toolchainError(
+      'toolchain_artifact_missing',
+      `the ${artifact} (${spec}) is not installed`,
+      missingRemedy(packageName, version, artifact),
+      { cause, artifact: spec },
+    );
+    try {
+      return requireFromPackage.resolve(spec);
+    } catch (defaultError) {
+      const walked = resolveThroughExportsMap(spec);
+      if (walked !== null) return walked;
+      throw missing(defaultError);
+    }
+  }
+
+  /** The package root for an installed dependency, found from its main
+   *  entry by walking up to the directory that owns its package.json. */
+  function packageRootOf(name) {
+    let main;
+    try {
+      main = requireFromPackage.resolve(name);
+    } catch {
+      return null;
+    }
+    let directory = dirname(main);
+    for (let depth = 0; depth < 4; depth++) {
+      if (existsSync(join(directory, 'package.json'))) return directory;
+      const parent = dirname(directory);
+      if (parent === directory) return null;
+      directory = parent;
+    }
+    return null;
+  }
+
+  function resolveThroughExportsMap(spec) {
+    const separator = spec.indexOf('/');
+    const name = spec.startsWith('@') ? spec.slice(0, spec.indexOf('/', separator + 1)) : spec.slice(0, separator);
+    const subpath = `.${spec.slice(name.length)}`;
+    const root = packageRootOf(name);
+    if (root === null) return null;
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    } catch {
+      return null;
+    }
+    const exports = manifest?.exports;
+    if (exports === null || typeof exports !== 'object') return null;
+    const entry = exports[subpath] ?? (subpath === '.' ? exports['.'] : undefined);
+    const picked = pickExportTarget(entry);
+    if (picked === null || picked.startsWith('.') === false) return null;
+    const path = resolve(root, picked);
+    return existsSync(path) ? path : null;
+  }
+
+  function pickExportTarget(entry, conditions = ['import', 'browser', 'default', 'node', 'require']) {
+    if (typeof entry === 'string') return entry;
+    if (entry === null || typeof entry !== 'object') return null;
+    for (const condition of conditions) {
+      if (condition in entry) {
+        const nested = pickExportTarget(entry[condition], conditions);
+        if (nested !== null) return nested;
+      }
+    }
+    return null;
+  }
+
+  async function requireInstalledFile(spec, packageName, version, artifact, file) {
+    let path;
+    if (file === undefined) {
+      path = resolveSpec(spec, packageName, version, artifact);
+    } else {
+      // A producer src row: the file lives inside its package but outside
+      // the owner's exports map, so resolve the package root from the
+      // spec and join the recorded file — never a directory traversal.
+      const packageRoot = packageRootOf(spec);
+      if (packageRoot === null) {
+        throw toolchainError(
+          'toolchain_artifact_missing',
+          `the ${artifact}'s package (${spec}) is not installed`,
+          missingRemedy(packageName, version, artifact),
+          { artifact: spec },
+        );
+      }
+      path = resolve(packageRoot, file);
+    }
+    const info = await stat(path).catch(() => null);
+    if (info === null || !info.isFile() || info.size === 0) {
+      throw toolchainError(
+        'toolchain_artifact_missing',
+        `the ${artifact} (${spec}) resolved to ${path}, which is not a non-empty file`,
+        missingRemedy(packageName, version, artifact),
+        { artifact: spec },
+      );
+    }
+    return path;
+  }
+
+  const runtimeRows = new Map(manifest.runtime.map((row) => [row.path, row]));
+
+  /** The producer a runtime row's npm package belongs to. Manifest rows
+   *  carry npm package names (@mr_hugo/pacer); the producers map and the
+   *  versions table speak producer names (pacer) — the remedy for a
+   *  missing artifact must name the version, so map back before lookup. */
+  function producerOf(packageName) {
+    if (packageName === PACER_PACKAGE || packageName.startsWith(`${PACER_PACKAGE}-`)) return 'pacer';
+    return packageName;
+  }
+
+  async function runtimeFile(relative) {
+    const row = runtimeRows.get(relative);
+    if (row === undefined) {
+      throw toolchainError(
+        'toolchain_artifact_missing',
+        `the installed runtime has no ${relative}`,
+        'Reinstall animader-cli; the release manifest does not describe this runtime file.',
+      );
+    }
+    const packageName = row.package ?? row.spec.split('/').slice(0, row.spec.startsWith('@') ? 2 : 1).join('/');
+    const producer = producerOf(packageName);
+    const version = manifest.producers?.[producer]?.version ?? versions[producer] ?? '*';
+    return requireInstalledFile(row.spec, packageName, version, relative, row.file);
+  }
+
+  const pnginePlatform = PNGINE_PLATFORM_PACKAGES[platform];
+  const pacerPlatform = PACER_PLATFORM_PACKAGES[platform];
+  if (pnginePlatform === undefined || pacerPlatform === undefined) {
+    throw toolchainError(
+      'toolchain_platform_unsupported',
+      `no platform package is declared for ${platform}`,
+      `This animader-cli build cannot run on ${platform}; check the release matrix for tested targets.`,
+    );
+  }
+
+  const descriptor = {
+    mode: 'installed',
+    identity: `installed toolchain ${manifest.toolchainVersion} for ${platform}`
+      + ` (animader ${versions.animader}, pngine ${versions.pngine}, pacer ${versions.pacer}, esbuild ${versions.esbuild})`,
+    target: { ...manifest.target },
+    manifest,
+    runtime: {
+      kind: 'map',
+      /** Sync path answer over the manifest rows; a missing package or
+       *  file throws the named toolchain_artifact_missing error. */
+      path(relative) {
+        const row = runtimeRows.get(relative);
+        if (row === undefined) {
+          throw toolchainError(
+            'toolchain_artifact_missing',
+            `the installed runtime has no ${relative}`,
+            'Reinstall animader-cli; the release manifest does not describe this runtime file.',
+          );
+        }
+        if (row.file !== undefined) {
+          const packageRoot = packageRootOf(row.spec);
+          if (packageRoot === null) {
+            throw toolchainError(
+              'toolchain_artifact_missing',
+              `the installed runtime's ${relative} has no package (${row.spec}) installed`,
+              `Reinstall animader-cli; the ${row.spec} package carries this runtime file.`,
+            );
+          }
+          return resolve(packageRoot, row.file);
+        }
+        return resolveSpec(row.spec, row.package ?? row.spec, '*', relative);
+      },
+      async requireFile(relative) { return runtimeFile(relative); },
+      async files() {
+        const files = [];
+        for (const row of manifest.runtime) {
+          files.push({ path: row.path, source: await runtimeFile(row.path) });
+        }
+        return files;
+      },
+    },
+    pngine: {
+      cli: await platformBinary(pnginePlatform, versions.pngine, 'bin/pngine', 'pngine native CLI'),
+      viewer: await requireInstalledFile('pngine/viewer', 'pngine', versions.pngine, 'pngine viewer bundle'),
+      core: await requireInstalledFile('pngine/core', 'pngine', versions.pngine, 'pngine core reflection reader'),
+      uniformTypeName: await packageFile(pkgRoot, MANIFEST_RELATIVE_PATH.replace('manifest.json', 'uniform-type-name.js'), 'the packaged uniformTypeName helper'),
+    },
+    pacer: {
+      cli: await platformBinary(pacerPlatform, versions.pacer, 'bin/pacer', 'pacer native pack CLI'),
+      index: await requireInstalledFile(PACER_PACKAGE, PACER_PACKAGE, versions.pacer, 'pacer compile driver'),
+      route: await requireInstalledFile(`${PACER_PACKAGE}/route`, PACER_PACKAGE, versions.pacer, 'pacer route writer'),
+      rt: await requireInstalledFile(`${PACER_PACKAGE}/rt`, PACER_PACKAGE, versions.pacer, 'pacer playback runtime'),
+      pacerWasm: await requireInstalledFile(`${PACER_PACKAGE}/pacer.wasm`, PACER_PACKAGE, versions.pacer, 'pacer compile wasm'),
+      pacerRtWasm: await requireInstalledFile(`${PACER_PACKAGE}/pacer-rt.wasm`, PACER_PACKAGE, versions.pacer, 'pacer playback wasm'),
+    },
+    animader: {
+      wasm: await requireInstalledFile('animader/wasm', 'animader', versions.animader, 'animader host wasm'),
+      piece: await requireInstalledFile('animader/piece', 'animader', versions.animader, 'animader piece host'),
+    },
+    versions,
+    esbuild: {
+      require() {
+        try {
+          return requireFromPackage('esbuild');
+        } catch (cause) {
+          throw toolchainError(
+            'toolchain_artifact_missing',
+            'the pinned esbuild is not installed',
+            missingRemedy('esbuild', versions.esbuild ?? '*', 'release bundler'),
+            { cause },
+          );
+        }
+      },
+    },
+    async verifyRuntime() {
+      const rows = [];
+      for (const row of manifest.runtime) {
+        const path = await runtimeFile(row.path);
+        const bytes = await readFile(path);
+        if (bytes.byteLength !== row.bytes || sha256(bytes) !== row.sha256) {
+          throw toolchainError(
+            'toolchain_content_drift',
+            `the installed ${row.path} does not match the release manifest (${sha256(bytes)} vs ${row.sha256})`,
+            'Reinstall animader-cli; installed artifacts must match the tested release manifest byte for byte.',
+          );
+        }
+        rows.push({ path: row.path, source: row.spec, sha256: row.sha256, bytes: row.bytes });
+      }
+      return {
+        format: VENDOR_FORMAT,
+        files: rows,
+        digest: manifest.digest,
+        provenance: {
+          format: VENDOR_FORMAT,
+          producers: manifest.producers,
+          files: rows,
+          digest: manifest.digest,
+        },
+      };
+    },
+    async verifyTools() {
+      const rows = [];
+      for (const entry of Object.values(manifest.tools)) {
+        const path = await platformBinary(entry.package, entry.version ?? '*', entry.file, entry.artifact ?? 'native tool');
+        const bytes = await readFile(path);
+        if (entry.sha256 !== undefined && (bytes.byteLength !== entry.bytes || sha256(bytes) !== entry.sha256)) {
+          throw toolchainError(
+            'toolchain_content_drift',
+            `the installed ${entry.package} ${entry.file} does not match the release manifest`,
+            'Reinstall animader-cli; installed native tools must match the tested release manifest byte for byte.',
+          );
+        }
+        rows.push({ name: entry.package, path, bytes: bytes.byteLength, sha256: sha256(bytes) });
+      }
+      return { tools: rows };
+    },
+    async licenseText() {
+      return readFile(join(pkgRoot, 'toolchain', 'licenses', 'animader.txt'), 'utf8');
+    },
+    async producerVersion(name) {
+      return versions[name] ?? null;
+    },
+  };
+  return descriptor;
+
+  async function platformBinary(packageName, version, file, artifact) {
+    let packageJsonPath;
+    try {
+      packageJsonPath = requireFromPackage.resolve(`${packageName}/package.json`);
+    } catch (cause) {
+      throw toolchainError(
+        'toolchain_artifact_missing',
+        `the platform package ${packageName} is not installed, so the ${artifact} is missing`,
+        `Install ${packageName}@${version} (reinstall animader-cli so npm's platform selection pulls it), or use a target it ships.`,
+        { cause, artifact },
+      );
+    }
+    const binary = join(dirname(packageJsonPath), file);
+    const info = await stat(binary).catch(() => null);
+    if (info === null || !info.isFile()) {
+      throw toolchainError(
+        'toolchain_artifact_missing',
+        `the platform package ${packageName} is installed but carries no ${file}`,
+        `Reinstall ${packageName}@${version}; its packed binary is missing or stripped.`,
+      );
+    }
+    return binary;
+  }
+
+  async function packageFile(root, relative, what) {
+    const path = join(root, relative);
+    const info = await stat(path).catch(() => null);
+    if (info === null || !info.isFile()) {
+      throw toolchainError(
+        'toolchain_artifact_missing',
+        `${what} is missing from this installation: ${relative}`,
+        'Reinstall animader-cli; the release assembly ships this file inside the package.',
+      );
+    }
+    return path;
+  }
+}
+
+/**
+ * The identity line `animader --version` prints. Contributor mode keeps its
+ * honest label; installed mode names the manifest's tested combination.
+ *
+ * @param {{env?: object, pkgRoot?: string}} [options]
+ */
+export async function toolchainIdentity({ env = process.env, pkgRoot = PKG_ROOT } = {}) {
+  const toolchain = await resolveToolchain({ env, pkgRoot });
+  return toolchain.identity;
+}