wyvrnpm 2.12.2 → 2.13.11

package/src/providers/s3.js

@@ -112,6 +112,18 @@ class S3Provider extends BaseProvider {
     }
   }
 
+  async _getBytes(client, bucket, key, GetObjectCommand) {
+    try {
+      const resp = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+      const chunks = [];
+      for await (const chunk of resp.Body) chunks.push(chunk);
+      return Buffer.concat(chunks);
+    } catch (err) {
+      if (err.name === 'NoSuchKey' || err.$metadata?.httpStatusCode === 404) return null;
+      throw err;
+    }
+  }
+
   async _downloadToFile(client, bucket, key, destPath, GetObjectCommand) {
     try {
       const resp = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
@@ -180,8 +192,9 @@ class S3Provider extends BaseProvider {
   async v2Publish(files, options) {
     const {
       source, name, version, profileHash, buildSettings,
-      contentSha256, gitSha, gitRepo, publishedLock, awsProfile,
-      updateLatest = true, uploadedBy,
+      contentSha256, gitSha, gitRepo, awsProfile,
+      updateLatest = true,
+      artefactConfigs,
     } = options;
     const { PutObjectCommand, GetObjectCommand } = this._loadSdk();
     const client = this._makeClient(awsProfile);
@@ -190,32 +203,54 @@ class S3Provider extends BaseProvider {
     const v2root    = this._key(prefix, 'v2', name);
     const buildRoot = `${v2root}/${version}/${profileHash}`;
 
-    // 1) Upload zip
-    await this._putFile(client, bucket, `${buildRoot}/wyvrn.zip`, files.zip, 'application/zip', PutObjectCommand);
-
-    // 2) Upload enriched wyvrn.json.
-    //    buildSettings is stored for debugging purposes only.
-    //    Dependencies are published verbatim from wyvrn.json — ranges stay as
-    //    ranges so consumers can intersect them with their own. The author's
-    //    lockfile snapshot is preserved in `publishedLock` for audit.
-    const rawManifest = JSON.parse(fs.readFileSync(files.manifest, 'utf8'));
-    const v2Meta = {
-      ...rawManifest,
-      schemaVersion: 2,
-      profileHash,
-      buildSettings,
-      contentSha256,
-      gitSha:      gitSha  ?? null,
-      gitRepo:     gitRepo ?? null,
-      publishedAt: new Date().toISOString(),
-      ...(publishedLock && Object.keys(publishedLock).length > 0 ? { publishedLock } : {}),
-      ...(uploadedBy ? { uploadedBy } : {}),
-    };
-    await this._putBuffer(
+    const sliceConfigs =
+      (artefactConfigs && Object.keys(artefactConfigs).length > 0)
+        ? Object.keys(artefactConfigs).sort()
+        : null;
+
+    // 1) Upload zip(s) — fat or per-config slices.
+    if (sliceConfigs) {
+      if (!files.artefactZips || typeof files.artefactZips !== 'object') {
+        throw new Error('v2Publish: artefactConfigs supplied but files.artefactZips missing');
+      }
+      for (const config of sliceConfigs) {
+        const slicePath = files.artefactZips[config];
+        if (!slicePath) {
+          throw new Error(
+            `v2Publish: artefactConfigs declares "${config}" but files.artefactZips["${config}"] is missing`,
+          );
+        }
+        await this._putFile(
+          client, bucket, `${buildRoot}/wyvrn-${config}.zip`,
+          slicePath, 'application/zip', PutObjectCommand,
+        );
+      }
+    } else {
+      if (!files.zip) {
+        throw new Error('v2Publish: files.zip required for fat-zip publish');
+      }
+      await this._putFile(client, bucket, `${buildRoot}/wyvrn.zip`, files.zip, 'application/zip', PutObjectCommand);
+    }
+
+    // 2) Upload wyvrn.json VERBATIM from `files.manifest`. The publisher
+    //    (commands/publish.js, upload-built.js) builds the v2Meta body
+    //    via src/v2-meta.js so the signed manifestSha256 matches what
+    //    consumers compute from v2GetMeta. Providers MUST NOT mutate.
+    await this._putFile(
       client, bucket, `${buildRoot}/wyvrn.json`,
-      Buffer.from(JSON.stringify(v2Meta, null, 2)), 'application/json', PutObjectCommand,
+      files.manifest, 'application/json', PutObjectCommand,
     );
 
+    // 2.5) signing files (S1) — written between manifest and versions.json
+    //      so a partial-failure crash never leaves a sig-less entry visible
+    //      in versions.json. Both files optional; mode.json governs.
+    if (files.attPath) {
+      await this._putFile(client, bucket, `${buildRoot}/wyvrn.att.json`, files.attPath, 'application/json', PutObjectCommand);
+    }
+    if (files.sigPath) {
+      await this._putFile(client, bucket, `${buildRoot}/wyvrn.sig`,      files.sigPath, 'application/json', PutObjectCommand);
+    }
+
     // 3) source.json
     if (gitSha || gitRepo) {
       await this._putBuffer(
@@ -225,16 +260,21 @@ class S3Provider extends BaseProvider {
       );
     }
 
-    // 4) Read-modify-write versions.json
+    // 4) Read-modify-write versions.json. Per-profile entries hold
+    //    either `contentSha256` (fat zip) or `configs` (slice publish).
     let versionsIdx = await this._getJson(client, bucket, `${v2root}/versions.json`, GetObjectCommand)
       ?? { name, latest: version, versions: {} };
     if (!versionsIdx.versions) versionsIdx.versions = {};
     if (!versionsIdx.versions[version]) versionsIdx.versions[version] = { profiles: {} };
-    versionsIdx.versions[version].profiles[profileHash] = {
-      contentSha256,
+
+    const profileEntry = {
       publishedAt: new Date().toISOString(),
       buildSettings,
     };
+    if (sliceConfigs) profileEntry.configs       = sliceConfigs;
+    else              profileEntry.contentSha256 = contentSha256;
+    versionsIdx.versions[version].profiles[profileHash] = profileEntry;
+
     if (gitSha || gitRepo) {
       versionsIdx.versions[version].source = { gitRepo: gitRepo ?? null, gitSha: gitSha ?? null };
     }
@@ -246,9 +286,12 @@ class S3Provider extends BaseProvider {
 
     // 5) latest.json — skipped for consumer uploads (see FileProvider note).
     if (updateLatest) {
+      const latestEntry = { version, profileHash };
+      if (sliceConfigs) latestEntry.configs       = sliceConfigs;
+      else              latestEntry.contentSha256 = contentSha256;
       await this._putBuffer(
         client, bucket, `${v2root}/latest.json`,
-        Buffer.from(JSON.stringify({ version, profileHash, contentSha256 })),
+        Buffer.from(JSON.stringify(latestEntry)),
         'application/json', PutObjectCommand,
       );
     }
@@ -270,13 +313,42 @@ class S3Provider extends BaseProvider {
     return this._getJson(client, bucket, key, GetObjectCommand);
   }
 
-  async v2DownloadZip({ source, name, version, profileHash, awsProfile }, destPath) {
+  async v2DownloadZip({ source, name, version, profileHash, sliceConfig, awsProfile }, destPath) {
     const { GetObjectCommand } = this._loadSdk();
     const client = this._makeClient(awsProfile);
     const { bucket, prefix } = this._parseSource(source);
-    const key = this._key(prefix, 'v2', name, version, profileHash, 'wyvrn.zip');
+    const filename = sliceConfig ? `wyvrn-${sliceConfig}.zip` : 'wyvrn.zip';
+    const key = this._key(prefix, 'v2', name, version, profileHash, filename);
     return this._downloadToFile(client, bucket, key, destPath, GetObjectCommand);
   }
+
+  // ── S1 signing surface ────────────────────────────────────────────────────
+
+  async v2GetAttestation({ source, name, version, profileHash, awsProfile }) {
+    const { GetObjectCommand } = this._loadSdk();
+    const client = this._makeClient(awsProfile);
+    const { bucket, prefix } = this._parseSource(source);
+    const key = this._key(prefix, 'v2', name, version, profileHash, 'wyvrn.att.json');
+    return this._getBytes(client, bucket, key, GetObjectCommand);
+  }
+
+  async v2GetSignature({ source, name, version, profileHash, awsProfile }) {
+    const { GetObjectCommand } = this._loadSdk();
+    const client = this._makeClient(awsProfile);
+    const { bucket, prefix } = this._parseSource(source);
+    const key = this._key(prefix, 'v2', name, version, profileHash, 'wyvrn.sig');
+    return this._getBytes(client, bucket, key, GetObjectCommand);
+  }
+
+  async v2GetTrustAnchor({ source, awsProfile }) {
+    const { GetObjectCommand } = this._loadSdk();
+    const client = this._makeClient(awsProfile);
+    const { bucket, prefix } = this._parseSource(source);
+    const keys = await this._getJson(client, bucket, this._key(prefix, 'v2', '.trust', 'keys.json'), GetObjectCommand);
+    const mode = await this._getJson(client, bucket, this._key(prefix, 'v2', '.trust', 'mode.json'), GetObjectCommand);
+    if (keys === null && mode === null) return null;
+    return { keys, mode };
+  }
 }
 
 module.exports = S3Provider;

package/src/publish/slice.js

@@ -0,0 +1,414 @@
+'use strict';
+
+// Per-config artefact slicing — phase 1 (inventory-driven).
+//
+// Author opts a recipe in via `build.publishPerConfig: true`; the
+// publish command then calls into this module with the unified install
+// tree path and the recipe's declared `build.configs`. Output is one
+// zip per declared config under
+// `{source}/v2/{name}/{version}/{profileHash}/wyvrn-<Config>.zip`,
+// each carrying:
+//
+//   - all "shared" install-tree files (headers, license,
+//     `*Config.cmake`, base `*Targets.cmake`)
+//   - the per-config files for THIS config only
+//     (whichever paths CMake's `*Targets-<config>.cmake` claims via
+//     IMPORTED_LOCATION_<CONFIG>, IMPORTED_IMPLIB_<CONFIG>, or
+//     IMPORTED_SONAME_<CONFIG>)
+//
+// Re-extracting multiple slices into one `wyvrn_internal/<name>/`
+// directory therefore reconstructs the full multi-config install
+// tree — that's the invariant a VS-generator consumer relies on when
+// it asks for both Release and Debug slices.
+//
+// ─── Classification: WHY inventory and not path-segments ──────────────────
+// CMake supports two conventions for distinguishing per-config binaries:
+//   1. MSVC multi-config:  `lib/<Config>/foo.lib` (per-config subdirs)
+//   2. Postfix convention: `lib/foo.lib` (Release) vs `lib/food.lib`
+//      (Debug, via CMAKE_DEBUG_POSTFIX="d") — all in flat lib/
+// gRPC uses the postfix convention. A path-segment heuristic would
+// dump every binary into the shared bucket and produce four byte-
+// identical slice zips, defeating the entire feature. The only signal
+// that captures both conventions correctly is CMake's own export
+// inventory: `*Targets-<config>.cmake` lists each file the consumer
+// should link for that config.
+//
+// IMPORTED_CONFIGURATIONS regeneration is intentionally a no-op in
+// phase 1. Modern CMake (3.10+) emits the base `*Targets.cmake` with
+// a `file(GLOB ... *Targets-*.cmake)` pattern, so the runtime
+// `IMPORTED_CONFIGURATIONS` set is built up from whichever per-config
+// files happen to be present at consumer extract time.
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+
+const { StreamingZipWriter } = require('../zip-stream');
+
+// Phase 1 covers only the four canonical CMake configurations.
+const VALID_CMAKE_CONFIGS = ['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel'];
+const VALID_CONFIG_LOWER  = new Map(VALID_CMAKE_CONFIGS.map((c) => [c.toLowerCase(), c]));
+
+/**
+ * Match a string to a canonical CMake config name (case-insensitive).
+ * Returns the canonical name (`'Release'`) or `null`.
+ *
+ * @param {unknown} s
+ * @returns {string|null}
+ */
+function matchCanonicalConfig(s) {
+  if (typeof s !== 'string') return null;
+  return VALID_CONFIG_LOWER.get(s.toLowerCase()) ?? null;
+}
+
+// CMake's install(EXPORT) generator emits per-config target files
+// matching this pattern. Both PascalCase ('XTargets-release.cmake')
+// and kebab-case ('x-targets-release.cmake') variants appear in
+// real-world packages — gRPC's bundled tree uses both depending on
+// the sub-package's CMake style (absl: PascalCase, c-ares + protobuf
+// + utf8_range: kebab-case). The match is case-insensitive on the
+// "Targets" word AND on the config tag.
+const EXPORT_FILE_RE = /(?:Targets|targets)-([A-Za-z0-9_]+)\.cmake$/i;
+
+/**
+ * Build the regex that captures every IMPORTED_*_<CONFIG> path in a
+ * `*Targets-<config>.cmake` body. Three property variants name on-
+ * disk artefacts: IMPORTED_LOCATION_<CONFIG> (every static lib +
+ * executable), IMPORTED_IMPLIB_<CONFIG> (Windows DLL import libs),
+ * IMPORTED_SONAME_<CONFIG> (Linux .so versioning). Paths are always
+ * rooted at the install dir via the literal `${_IMPORT_PREFIX}`
+ * variable; CMake guarantees this in install(EXPORT) output.
+ *
+ * @param {string} canonicalConfig
+ * @returns {RegExp}
+ */
+function makeImportedPropertyRegex(canonicalConfig) {
+  const upper = canonicalConfig.toUpperCase();
+  return new RegExp(
+    `IMPORTED_(?:LOCATION|IMPLIB|SONAME)_${upper}\\s+"\\$\\{_IMPORT_PREFIX\\}/([^"]+)"`,
+    'g',
+  );
+}
+
+/**
+ * Parse one *Targets-<config>.cmake file's contents and return the
+ * relPaths it declares belong to that config. Exported for unit tests
+ * that lock down the regex against representative real-world files.
+ *
+ * @param {string} text             Contents of the export file.
+ * @param {string} canonicalConfig  e.g. 'Release'.
+ * @returns {Set<string>}
+ */
+function parseExportFile(text, canonicalConfig) {
+  const re = makeImportedPropertyRegex(canonicalConfig);
+  const out = new Set();
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    // CMake export files always use forward-slash; preserve as-is.
+    out.add(m[1]);
+  }
+  return out;
+}
+
+/**
+ * Walk `installDir`, find every `*Targets-<config>.cmake`, parse the
+ * IMPORTED_*_<CONFIG> entries inside, and produce the per-config file
+ * inventory.
+ *
+ * Output:
+ *   - `perConfigFiles[<canonical>]`: Set of relPaths CMake declared
+ *     belong to that config. Includes the export file itself.
+ *   - `unknownTags`: Map<rawTag, relPath[]> — `*Targets-<custom>.cmake`
+ *     files whose tag isn't a canonical CMake config (e.g. "asan"
+ *     from a custom build_type). Audit turns this into a fail.
+ *   - `exportFilesFound`: count of valid (canonical) export files.
+ *     0 → "tree has no install(EXPORT) output, can't slice".
+ *
+ * @param {string} installDir
+ * @returns {{
+ *   perConfigFiles:   Record<string, Set<string>>,
+ *   unknownTags:      Map<string, string[]>,
+ *   exportFilesFound: number,
+ * }}
+ */
+function buildInventory(installDir) {
+  /** @type {Record<string, Set<string>>} */
+  const perConfigFiles = Object.create(null);
+  for (const cfg of VALID_CMAKE_CONFIGS) perConfigFiles[cfg] = new Set();
+  /** @type {Map<string, string[]>} */
+  const unknownTags = new Map();
+  /** @type {Array<{ rel: string, full: string, canonical: string }>} */
+  const exportFiles = [];
+
+  function walk(current) {
+    for (const entry of fs.readdirSync(current).sort()) {
+      const full = path.join(current, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) { walk(full); continue; }
+      const rel = path.relative(installDir, full).replace(/\\/g, '/');
+      const m = path.basename(rel).match(EXPORT_FILE_RE);
+      if (!m) continue;
+      const tag = m[1];
+      const canonical = matchCanonicalConfig(tag);
+      if (canonical === null) {
+        if (!unknownTags.has(tag)) unknownTags.set(tag, []);
+        unknownTags.get(tag).push(rel);
+        continue;
+      }
+      exportFiles.push({ rel, full, canonical });
+    }
+  }
+  walk(installDir);
+
+  for (const { rel, full, canonical } of exportFiles) {
+    let text;
+    try {
+      text = fs.readFileSync(full, 'utf8');
+    } catch (err) {
+      throw new Error(`slice: cannot read export file ${rel}: ${err.message}`);
+    }
+    const claimed = parseExportFile(text, canonical);
+    for (const p of claimed) perConfigFiles[canonical].add(p);
+    // The export file itself is per-config — it's the file that names
+    // its config's IMPORTED_LOCATION entries, so it ships with that slice.
+    perConfigFiles[canonical].add(rel);
+  }
+
+  return { perConfigFiles, unknownTags, exportFilesFound: exportFiles.length };
+}
+
+/**
+ * Some files (protoc.exe, gRPC plugin executables) are referenced by
+ * the SAME path from every config's export file — they're config-
+ * neutral on disk despite being mentioned per-config. Detect via
+ * "claimed by ≥2 configs at the same relPath" and demote to shared.
+ * Mutates `perConfigFiles` in place; returns the demoted set for
+ * diagnostics.
+ *
+ * @param {Record<string, Set<string>>} perConfigFiles
+ * @returns {Set<string>}
+ */
+function rectifyMultiConfigFiles(perConfigFiles) {
+  /** @type {Map<string, Set<string>>} */
+  const fileToConfigs = new Map();
+  for (const cfg of VALID_CMAKE_CONFIGS) {
+    for (const f of perConfigFiles[cfg]) {
+      if (!fileToConfigs.has(f)) fileToConfigs.set(f, new Set());
+      fileToConfigs.get(f).add(cfg);
+    }
+  }
+  const demoted = new Set();
+  for (const [f, configs] of fileToConfigs) {
+    if (configs.size > 1) {
+      for (const cfg of configs) perConfigFiles[cfg].delete(f);
+      demoted.add(f);
+    }
+  }
+  return demoted;
+}
+
+/**
+ * Walk `installDir` and produce a slice plan driven by the CMake
+ * export inventory. Files mentioned in `IMPORTED_LOCATION_<CONFIG>`
+ * (or IMPLIB / SONAME) entries land in that config's bucket; files
+ * mentioned by every config at the same path are demoted to shared
+ * (config-neutral binaries); everything else is shared.
+ *
+ * @param {string} installDir
+ * @returns {{
+ *   sharedFiles:      Array<{ fullPath: string, relPath: string }>,
+ *   perConfigFiles:   Record<string, Array<{ fullPath: string, relPath: string }>>,
+ *   unknownConfigs:   Map<string, string[]>,
+ *   exportFilesFound: number,
+ *   demotedFiles:     Set<string>,
+ * }}
+ */
+function planSlice(installDir) {
+  const inventory   = buildInventory(installDir);
+  const demotedFiles = rectifyMultiConfigFiles(inventory.perConfigFiles);
+
+  // Index relPath → config for O(1) classification on the file walk.
+  const fileToConfig = new Map();
+  for (const cfg of VALID_CMAKE_CONFIGS) {
+    for (const f of inventory.perConfigFiles[cfg]) fileToConfig.set(f, cfg);
+  }
+
+  // Files matching `*Targets-<custom>.cmake` (non-canonical tag) MUST
+  // NOT leak into shared — they'd ship in every slice and consumers
+  // would inherit symbols they didn't ask for. The audit fails before
+  // any zip is written, but be defence-in-depth: collect them here so
+  // the walk can skip them entirely.
+  const unknownTagPaths = new Set();
+  for (const paths of inventory.unknownTags.values()) {
+    for (const p of paths) unknownTagPaths.add(p);
+  }
+
+  const sharedFiles = [];
+  /** @type {Record<string, Array<{ fullPath: string, relPath: string }>>} */
+  const perConfigBuckets = Object.create(null);
+  for (const cfg of VALID_CMAKE_CONFIGS) perConfigBuckets[cfg] = [];
+
+  function walk(current) {
+    for (const entry of fs.readdirSync(current).sort()) {
+      const full = path.join(current, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) { walk(full); continue; }
+      const rel = path.relative(installDir, full).replace(/\\/g, '/');
+      if (unknownTagPaths.has(rel)) continue;     // unknown-tag exports never ship
+      const cfg = fileToConfig.get(rel);
+      if (cfg) perConfigBuckets[cfg].push({ fullPath: full, relPath: rel });
+      else     sharedFiles.push({ fullPath: full, relPath: rel });
+    }
+  }
+  walk(installDir);
+
+  return {
+    sharedFiles,
+    perConfigFiles:   perConfigBuckets,
+    unknownConfigs:   inventory.unknownTags,
+    exportFilesFound: inventory.exportFilesFound,
+    demotedFiles,
+  };
+}
+
+/**
+ * Audit a slice plan against the recipe's declared `build.configs`.
+ * Throws on any of:
+ *   - No `*Targets-<canonical>.cmake` files in the install tree at
+ *     all → can't slice (header-only or unexported package; recipe
+ *     should set publishPerConfig: false, or the source CMakeLists
+ *     should add install(TARGETS … EXPORT …)).
+ *   - Filenames matching `*Targets-<tag>.cmake` whose tag isn't
+ *     canonical (typo / unsupported custom build type).
+ *   - A declared config with zero entries in the inventory (forgot
+ *     `cmake --install --config <X>`, or the export file has no
+ *     IMPORTED_LOCATION_<CONFIG> entries at all).
+ *   - The inventory has a canonical config not declared in
+ *     `build.configs` (install-tree drifted from recipe).
+ *
+ * Auditing happens BEFORE any zips are written so a misconfigured
+ * publish exits early.
+ *
+ * @param {ReturnType<planSlice>} plan
+ * @param {string[]} declaredConfigs
+ */
+function auditSlicePlan(plan, declaredConfigs) {
+  if (plan.exportFilesFound === 0) {
+    throw new Error(
+      'slice audit: install tree contains no *Targets-<config>.cmake files. ' +
+      'Per-config slicing requires CMake install(EXPORT ...) output. ' +
+      'Either set build.publishPerConfig: false, or add install(TARGETS … EXPORT …) ' +
+      'to the source CMakeLists so the install tree carries per-config target inventories.',
+    );
+  }
+
+  if (plan.unknownConfigs.size > 0) {
+    const summary = [...plan.unknownConfigs.entries()]
+      .map(([tag, paths]) => `${JSON.stringify(tag)} (${paths.length} file${paths.length === 1 ? '' : 's'})`)
+      .join(', ');
+    throw new Error(
+      `slice audit: install tree contains *Targets-<tag>.cmake files with non-canonical ` +
+      `config tags: ${summary}. Phase 1 supports only Debug / Release / RelWithDebInfo / MinSizeRel.`,
+    );
+  }
+
+  const declared = new Set(declaredConfigs);
+  for (const cfg of declaredConfigs) {
+    if (!VALID_CONFIG_LOWER.has(cfg.toLowerCase())) {
+      throw new Error(
+        `slice audit: build.configs contains ${JSON.stringify(cfg)}, which is not a ` +
+        `canonical CMake config name`,
+      );
+    }
+    if (plan.perConfigFiles[cfg].length === 0) {
+      throw new Error(
+        `slice audit: build.configs declares ${JSON.stringify(cfg)} but no ` +
+        `IMPORTED_LOCATION_${cfg.toUpperCase()} (or _IMPLIB_/_SONAME_) entries were found in ` +
+        `any *Targets-${cfg.toLowerCase()}.cmake. Did you run "wyvrnpm build --config ${cfg} --install"?`,
+      );
+    }
+  }
+
+  for (const cfg of VALID_CMAKE_CONFIGS) {
+    if (plan.perConfigFiles[cfg].length > 0 && !declared.has(cfg)) {
+      throw new Error(
+        `slice audit: install tree has ${plan.perConfigFiles[cfg].length} file(s) for config ` +
+        `${JSON.stringify(cfg)} but build.configs does not declare it. ` +
+        `Either add ${JSON.stringify(cfg)} to build.configs, or "wyvrnpm clean" and rebuild ` +
+        `with only the declared configs.`,
+      );
+    }
+  }
+}
+
+/**
+ * Build the (shared ∪ per-config[config]) file list for one slice in
+ * deterministic relPath order. archiver preserves insertion order, so
+ * the same plan + same input bytes produce a byte-identical zip across
+ * runs and across machines.
+ *
+ * @param {ReturnType<planSlice>} plan
+ * @param {string} config
+ * @returns {Array<{ fullPath: string, relPath: string }>}
+ */
+function buildSliceFileList(plan, config) {
+  if (!Object.prototype.hasOwnProperty.call(plan.perConfigFiles, config)) {
+    throw new Error(`buildSliceFileList: unknown config ${JSON.stringify(config)}`);
+  }
+  const merged = [...plan.sharedFiles, ...plan.perConfigFiles[config]];
+  merged.sort((a, b) => (a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0));
+  return merged;
+}
+
+/**
+ * Build the slice zip for `config` and return its SHA-256 + size.
+ * Zip is closed before SHA is computed; the streaming hash reads from
+ * disk, so memory stays flat regardless of slice size.
+ *
+ * @param {object} args
+ * @param {ReturnType<planSlice>} args.plan
+ * @param {string} args.config
+ * @param {string} args.outZipPath
+ * @returns {Promise<{ sha256: string, sizeBytes: number, fileCount: number }>}
+ */
+async function buildSliceZip({ plan, config, outZipPath }) {
+  const files = buildSliceFileList(plan, config);
+  const zip = new StreamingZipWriter(outZipPath);
+  for (const { fullPath, relPath } of files) {
+    const zipDir = path.dirname(relPath).replace(/\\/g, '/');
+    zip.addLocalFile(fullPath, zipDir === '.' ? '' : zipDir);
+  }
+  await zip.finalize();
+  const { sha256, sizeBytes } = await sha256AndSize(outZipPath);
+  return { sha256, sizeBytes, fileCount: files.length };
+}
+
+/**
+ * Single-pass streaming SHA-256 + byte size of a file on disk.
+ *
+ * @param {string} filePath
+ * @returns {Promise<{ sha256: string, sizeBytes: number }>}
+ */
+function sha256AndSize(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    let sizeBytes = 0;
+    fs.createReadStream(filePath)
+      .on('data',  (chunk) => { hash.update(chunk); sizeBytes += chunk.length; })
+      .on('end',   () => resolve({ sha256: hash.digest('hex'), sizeBytes }))
+      .on('error', reject);
+  });
+}
+
+module.exports = {
+  parseExportFile,
+  buildInventory,
+  rectifyMultiConfigFiles,
+  matchCanonicalConfig,
+  planSlice,
+  auditSlicePlan,
+  buildSliceFileList,
+  buildSliceZip,
+  sha256AndSize,
+  VALID_CMAKE_CONFIGS,
+};