wyvrnpm 2.4.1 → 2.9.0

package/src/context.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * CommandContext — the shared per-invocation state every command consumes.
+ *
+ * Commands used to each re-read the manifest, re-resolve the profile name,
+ * re-read config, re-resolve auth, and each toggle JSON mode on the logger.
+ * The divergence was cheap at 11 commands; it starts costing real bugs
+ * once F3 (`tool_requires`) and F4 (build/host profile split) double the
+ * flag surface. See [claude/PLAN-COMMAND-CONTEXT.md](../claude/PLAN-COMMAND-CONTEXT.md).
+ *
+ * `buildContext(argv)` runs once at the top of each command. It:
+ *   - resolves filesystem anchors (rootDir, manifestPath)
+ *   - reads config once
+ *   - resolves the profile-name fallback chain + loads the profile
+ *   - parses CLI options + conf (format-level only; namespace allow-
+ *     listing happens later in the sinks that need it)
+ *   - sets JSON mode on the logger if --format=json
+ *   - exposes an auth helper pre-curried with CLI --token / --token-env
+ *   - exposes a lazy manifest getter (show never reads the manifest)
+ *
+ * `buildContext` does NOT do source filtering — each command has subtly
+ * different CLI shape there (publish takes name-or-URL, install/show
+ * take URL arrays, pin-resolution only matters for install). That
+ * stays per-command until a second feature shows the same duplication.
+ *
+ * Errors: `buildContext` THROWS on all input-validation failures. Each
+ * command wraps the call in one try/catch that does `log.error + exit`.
+ * This keeps buildContext unit-testable; behaviour from the user's
+ * point of view is unchanged.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { readConfig }        = require('./config');
+const { loadProfile }       = require('./profile');
+const { readManifest }      = require('./manifest');
+const { resolveSourceAuth } = require('./auth');
+const { parseCliOptions }   = require('./options');
+const { parseCliConf }      = require('./conf');
+const log                   = require('./logger');
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active profile name per the long-standing precedence:
+ *   --profile > config.defaultProfile > 'default'
+ */
+function resolveProfileName(argv, config) {
+  if (typeof argv.profile === 'string' && argv.profile.length > 0) {
+    return argv.profile;
+  }
+  if (typeof config.defaultProfile === 'string' && config.defaultProfile.length > 0) {
+    return config.defaultProfile;
+  }
+  return 'default';
+}
+
+/**
+ * Normalise CLI flags into the stable `ctx.flags` shape. Centralising
+ * defaults here means individual commands don't each re-apply
+ * `?? 'never'` / `?? 'Release'` / etc.
+ *
+ * Flags that are command-specific (argv.preset, argv.pkg, argv.clean,
+ * argv.verbose, argv.generator, argv.install, argv.installPrefix,
+ * argv.uploadSource, argv.autoInstall, argv.noGpgSign, ...) stay on
+ * argv and commands read them there. `ctx.argv` is the escape hatch.
+ */
+function normaliseFlags(argv) {
+  return {
+    format:      argv.format === 'json' ? 'json' : 'text',
+    dryRun:      argv.dryRun === true,
+    build:       argv.build ?? 'never',
+    uploadBuilt: argv.uploadBuilt === true,
+    force:       argv.force === true,
+    platform:    argv.platform ?? defaultPlatform(),
+    timeout:     typeof argv.timeout === 'number' ? argv.timeout : 300,
+  };
+}
+
+/**
+ * Default platform string when --platform is absent. Mirrors what
+ * bin/wyvrn.js passes when yargs applies its own default — keeping
+ * it here makes context.js testable without exercising the CLI layer.
+ */
+function defaultPlatform() {
+  if (process.platform === 'win32') {
+    return process.arch === 'ia32' ? 'win_x86' : 'win_x64';
+  }
+  if (process.platform === 'darwin') return 'macos';
+  return 'linux';
+}
+
+/**
+ * Produce a frozen `{ host, build }` profile pair. Today both point at
+ * the same resolved object — when F4 (build/host profile split) lands,
+ * only this function changes; every command reading `ctx.profiles.host`
+ * or `ctx.profiles.build` continues to work.
+ *
+ * The two sub-objects share a reference today. A regression test in
+ * tests/context.test.js asserts `ctx.profiles.host === ctx.profiles.build`
+ * — that test is expected to be removed (not fixed) when F4 makes them
+ * legitimately distinct.
+ */
+function resolveProfiles(argv, config) {
+  const name = resolveProfileName(argv, config);
+  const { profile, fromFile } = loadProfile(name);
+  const entry = Object.freeze({ name, profile, fromFile });
+  return Object.freeze({ host: entry, build: entry });
+}
+
+// ---------------------------------------------------------------------------
+// buildContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the per-invocation CommandContext.
+ *
+ * @param {object} argv - yargs-parsed argument map. Fields read:
+ *   root, manifest, profile, format, dryRun, build, uploadBuilt,
+ *   force, platform, timeout, token, tokenEnv, option, conf.
+ *   Command-specific fields pass through on ctx.argv unchanged.
+ *
+ * @returns {CommandContext}
+ *
+ * @throws on:
+ *   - parseCliOptions: malformed `-o pkg:name=value`
+ *   - parseCliConf:    malformed `--conf KEY=VALUE`
+ *   - loadProfile:     malformed profile JSON, cycle in `extends`, etc.
+ *
+ * Does NOT throw on:
+ *   - missing manifest (lazy — throws at first ctx.manifest access)
+ *   - missing config   (readConfig returns empty defaults)
+ *   - missing profile  (loadProfile falls back to detectProfile())
+ *   - missing --token-env value (resolveSourceAuth throws at ctx.auth.for time)
+ */
+function buildContext(argv = {}) {
+  // 1. Filesystem anchors — pure path math, no I/O.
+  const rootDir = path.resolve(argv.root ?? '.');
+  const manifestPath = path.resolve(
+    argv.manifest ?? path.join(rootDir, 'wyvrn.json'),
+  );
+
+  // 2. Config — sync, small file, every command needs at least .defaultProfile.
+  const config = readConfig();
+
+  // 3. Profile (F4-ready shape).
+  const profiles = resolveProfiles(argv, config);
+
+  // 4. CLI auth, kept as the raw pair. Actual token lookup happens
+  //    through ctx.auth.for(sourceEntry), which runs resolveSourceAuth
+  //    each time so --token-env misses surface at use (same as today).
+  const authCli = Object.freeze({
+    token:    typeof argv.token    === 'string' ? argv.token    : undefined,
+    tokenEnv: typeof argv.tokenEnv === 'string' ? argv.tokenEnv : undefined,
+  });
+
+  // 5. CLI options + conf — format-level parsing only. Namespace
+  //    allow-listing for conf happens later in resolveEffectiveConf;
+  //    options validation against the recipe's declared `allowed` set
+  //    happens at resolveEffectiveOptions time.
+  //    Both can throw — that's the contract: buildContext surfaces
+  //    input-level errors up front.
+  const cliOptions = parseCliOptions(argv.option);
+  const cliConf    = parseCliConf(argv.conf);
+
+  // 6. Flags.
+  const flags = normaliseFlags(argv);
+
+  // 7. JSON mode — side effect that must happen before the command
+  //    starts logging. Flipping the logger here means every command
+  //    that constructs a ctx gets JSON mode right automatically.
+  if (flags.format === 'json') log.setJsonMode(true);
+
+  // 8. Assemble.
+  const ctx = {
+    rootDir,
+    manifestPath,
+    cwd: process.cwd(),
+    profiles,
+    config,
+    auth: Object.freeze({
+      cli: authCli,
+      for: (sourceEntry) => resolveSourceAuth(authCli, sourceEntry ?? null),
+    }),
+    cliOptions,
+    cliConf,
+    flags,
+    argv,
+  };
+
+  // 9. Lazy manifest getter. Most commands need it; `show` does not.
+  //    Defining as a getter means:
+  //      - show pays nothing.
+  //      - other commands pay once, cached.
+  //      - an invalid manifest surfaces at first use, not at ctx
+  //        construction — so `show` never trips over it.
+  let manifestCache = null;
+  let manifestLoaded = false;
+  Object.defineProperty(ctx, 'manifest', {
+    configurable: false,
+    enumerable:   true,
+    get() {
+      if (!manifestLoaded) {
+        if (!fs.existsSync(manifestPath)) {
+          throw new Error(`Manifest not found: ${manifestPath}`);
+        }
+        manifestCache = readManifest(manifestPath);
+        manifestLoaded = true;
+      }
+      return manifestCache;
+    },
+  });
+
+  return ctx;
+}
+
+module.exports = {
+  buildContext,
+  // Exported for unit tests — kept out of the default import surface.
+  _helpers: {
+    resolveProfileName,
+    normaliseFlags,
+    defaultPlatform,
+    resolveProfiles,
+  },
+};

package/src/download.js

@@ -12,6 +12,7 @@ const { getProvider }           = require('./providers');
 const { evaluateCompat, pickBestCandidate, summarizeReasons } = require('./compat');
 const { buildFromSource }       = require('./build');
 const { uploadSourceBuiltArtefact } = require('./upload-built');
+const { assertAllSafeZipEntryNames } = require('./zip-safe');
 const log                       = require('./logger');
 
 // ---------------------------------------------------------------------------
@@ -59,17 +60,11 @@ async function tryDownloadFromSources(name, version, packageSources, platform, h
 //
 // PLAN-BUILD-MISSING phase 1: strict-by-default resolution.
 //
-// The v2 path is split in two:
-//
-//   tryV2Exact  — ONLY attempts the exact profile-hash match. Also returns
-//                 the versions index if the package exists in v2 (so the
-//                 caller can distinguish "v2 knows this package but not your
-//                 profile" from "v2 doesn't know this package at all").
-//
-//   tryV2Compat — the old OS+arch compatibility fallback. Now dead code on
-//                 the default path; only reachable via the escape-hatch env
-//                 var WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated — prints a
-//                 warning when used). Will be deleted in a future release.
+// tryV2Exact attempts the exact profile-hash match and, when it misses,
+// returns the versions index so the caller can distinguish "v2 knows this
+// package but not your profile" from "v2 doesn't know this package at all".
+// The declarative compat path (findCompatibleBuild) and the source-build
+// path consume that index.
 //
 
 /**
@@ -94,9 +89,43 @@ async function tryDownloadFromSources(name, version, packageSources, platform, h
  *   result?:            { contentSha256: string|null, gitSha: string|null, gitRepo: string|null, profileHash: string, source: string },
  *   indexFoundInSource: string|null,    // which source returned a versions index (null = none did)
  *   availableProfiles:  string[],       // profile hashes the registry HAS, for the error message
- *   versionsIndex?:     object,         // pre-fetched index, reusable by tryV2Compat
+ *   versionsIndex?:     object,         // pre-fetched index, reused by findCompatibleBuild + source-build
  * }>}
  */
+/**
+ * Locate a v2 versions.json index for (name, version) across the configured
+ * sources WITHOUT attempting to download the exact-match artefact. Used by
+ * the `--build=always` path (F9) where the registry index is needed purely
+ * to look up `gitRepo` / `gitSha` for source-build.
+ *
+ * Returns the same shape as tryV2Exact's miss case.
+ *
+ * @param {{ name: string, version: string }} dep
+ * @param {string[]} packageSources
+ * @param {object}   authOptions   { awsProfile?, token? }
+ */
+async function findV2Index(dep, packageSources, authOptions = {}) {
+  const { name, version } = dep;
+  const { awsProfile, token } = authOptions;
+
+  for (const source of packageSources) {
+    let provider;
+    try { provider = getProvider(source); } catch { continue; }
+
+    const idx = await provider.v2GetVersionsIndex({ source, name, awsProfile, token });
+    if (idx?.versions?.[version]?.profiles) {
+      return {
+        found:              false,
+        indexFoundInSource: source,
+        versionsIndex:      idx,
+        availableProfiles:  Object.keys(idx.versions[version].profiles),
+      };
+    }
+  }
+
+  return { found: false, indexFoundInSource: null, versionsIndex: null, availableProfiles: [] };
+}
+
 async function tryV2Exact(dep, packageSources, destZipPath, timeoutMs, authOptions = {}) {
   const { name, version, profileHash } = dep;
   const { awsProfile, token } = authOptions;
@@ -229,69 +258,20 @@ async function findCompatibleBuild({ name, version, consumerProfile, consumerOpt
   };
 }
 
-/**
- * LEGACY compat fallback — scan versions.json for a build with the same OS +
- * arch as the consumer's profile and use it. Reachable only via
- * WYVRNPM_ALLOW_LOOSE_COMPAT=1. Prints a deprecation warning whenever it
- * succeeds. Will be removed after one release cycle.
- *
- * @param {{ name: string, version: string, profile: import('./profile').WyvrnProfile }} dep
- * @param {object} versionsIndex     pre-fetched from tryV2Exact
- * @param {string} source            source URL that returned the index
- * @param {string} destZipPath
- * @param {number} timeoutMs
- * @param {object} authOptions
- * @returns {Promise<object|null>}   same shape as tryV2Exact.result, or null
- */
-async function tryV2Compat(dep, versionsIndex, source, destZipPath, timeoutMs, authOptions = {}) {
-  const { name, version, profile } = dep;
-  const { awsProfile, token } = authOptions;
-
-  let provider;
-  try { provider = getProvider(source); } catch { return null; }
-
-  const versionEntry = versionsIndex?.versions?.[version];
-  if (!versionEntry?.profiles) return null;
-
-  for (const [ph, buildEntry] of Object.entries(versionEntry.profiles)) {
-    const bp = buildEntry.buildSettings ?? buildEntry.profile;
-    if (!bp) continue;
-    if (bp.os   !== profile.os)   continue;
-    if (bp.arch !== profile.arch) continue;
-
-    log.warn(
-      `⚠  DEPRECATED loose-compat fallback (WYVRNPM_ALLOW_LOOSE_COMPAT=1):\n` +
-      `  ${name}@${version} — using build [${ph}] (${bp.compiler} ${bp['compiler.version']})\n` +
-      `  cppstd/runtime may differ from your profile. This fallback will be removed in the next release.`,
-    );
-    const ok = await provider.v2DownloadZip({ source, name, version, profileHash: ph, awsProfile, token }, destZipPath, timeoutMs);
-    if (ok) {
-      return {
-        contentSha256: buildEntry.contentSha256   ?? null,
-        gitSha:        versionEntry.source?.gitSha  ?? null,
-        gitRepo:       versionEntry.source?.gitRepo ?? null,
-        profileHash:   ph,
-        source,
-      };
-    }
-  }
-  return null;
-}
-
 /**
  * Build the structured error message shown when a package exists in the v2
  * registry but no build matches the consumer's profileHash.
  */
-function buildStrictMissMessage({ name, version, profileHash, availableProfiles, buildMode, loose }) {
+function buildStrictMissMessage({ name, version, profileHash, availableProfiles, buildMode }) {
   const lines = [
     `no v2 build of ${name}@${version} matches profile [${profileHash}]`,
     availableProfiles.length > 0
       ? `  Available builds on the registry: ${availableProfiles.map((p) => `[${p}]`).join(' ')}`
       : `  The registry lists no builds for this version.`,
   ];
-  if (buildMode === 'missing') {
+  if (buildMode === 'missing' || buildMode === 'always') {
     lines.push(
-      `  --build=missing source-build was attempted but did not produce a usable binary. ` +
+      `  --build=${buildMode} source-build was attempted but did not produce a usable binary. ` +
       `See the error above for details (missing git metadata, missing "build" section in source manifest, or compile failure).`,
     );
   } else {
@@ -299,11 +279,6 @@ function buildStrictMissMessage({ name, version, profileHash, availableProfiles,
       `  Fix: publish a build for your profile, switch to a compatible one, or rerun with --build=missing to source-build.`,
     );
   }
-  if (!loose) {
-    lines.push(
-      `  Escape hatch: WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated — accepts same OS+arch with possibly-different cppstd/runtime).`,
-    );
-  }
   return lines.join('\n');
 }
 
@@ -313,8 +288,17 @@ function buildStrictMissMessage({ name, version, profileHash, availableProfiles,
 
 async function extractZip(destZipPath, extractDir) {
   const zip = new StreamZip.async({ file: destZipPath });
-  await zip.extract(null, extractDir);
-  await zip.close();
+  try {
+    // Zip Slip defense-in-depth (EVALUATION.md S2): pre-scan entry names
+    // before handing them to node-stream-zip. Library is currently not
+    // known-vulnerable, but registry zips are the single most untrusted
+    // input on this path.
+    const entries = await zip.entries();
+    assertAllSafeZipEntryNames(Object.keys(entries), path.basename(destZipPath));
+    await zip.extract(null, extractDir);
+  } finally {
+    await zip.close();
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -328,12 +312,13 @@ async function extractZip(destZipPath, extractDir) {
  *   1. Exact profile-hash match from any configured v2 source → use it.
  *   2. Otherwise, if the package exists in v2 (versions.json returned an
  *      entry for this version) but nothing matches our profile:
- *        - Default: STRICT FAIL with a structured error. Does not fall back
- *          to v1 (that would silently accept a build with different settings).
- *        - `buildMode === 'missing'`: same strict fail for now; error hints
- *          at PLAN-BUILD-MISSING phase 3.
- *        - WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated escape hatch): try the
- *          old OS+arch compat fallback with a deprecation warning.
+ *        - Try declarative per-package compatibility (PLAN-BUILD-MISSING
+ *          phase 2); use the best compatible build if any.
+ *        - With `buildMode === 'missing'` and nothing compatible: clone the
+ *          source at gitRepo@gitSha and build it locally (phase 3).
+ *        - Otherwise: STRICT FAIL with a structured error. Does not fall
+ *          back to v1 (that would silently accept a build with different
+ *          settings).
  *   3. Otherwise (v2 doesn't know the package at all) → v1 legacy fallback.
  *
  * Legacy deps (plain `Map<name, version>`, no profile info) skip v2 entirely
@@ -362,15 +347,6 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     uploadStats,
   } = options;
 
-  if (buildMode === 'always') {
-    throw new Error(
-      '--build=always is not implemented (requires PLAN-BUILD-MISSING phase 3). ' +
-      'Use --build=never (default) or --build=missing.',
-    );
-  }
-
-  const looseCompatAllowed = process.env.WYVRNPM_ALLOW_LOOSE_COMPAT === '1';
-
   if (!fs.existsSync(razerDir)) {
     fs.mkdirSync(razerDir, { recursive: true });
   }
@@ -385,6 +361,11 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     const profileHash = isLegacyEntry ? null : (depInfoOrVersion.profileHash ?? null);
     const profile     = isLegacyEntry ? null : (depInfoOrVersion.profile     ?? null);
     const options     = isLegacyEntry ? null : (depInfoOrVersion.options     ?? null);
+    const pinnedSource = isLegacyEntry ? null : (depInfoOrVersion.pinnedSource ?? null);
+    // Per-dep source pin (EVALUATION.md S4). When set, restrict every
+    // lookup for this package to the pinned URL; no fan-out across
+    // configured sources.
+    const depSources = pinnedSource ? [pinnedSource.url] : packageSources;
 
     const extractDir  = path.join(razerDir, name);
     const versionFile = path.join(extractDir, '.wyvrn-version');
@@ -398,36 +379,43 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
       continue;
     }
 
-    // Skip if already at correct version + profile hash
+    // Skip if already at correct version + profile hash. `--build=always`
+    // (F9) bypasses this cache so the forced rebuild actually fires.
     if (fs.existsSync(extractDir)) {
-      const installedVersion = fs.existsSync(versionFile)
-        ? fs.readFileSync(versionFile, 'utf8').trim()
-        : null;
-      const installedMeta = fs.existsSync(metaFile)
-        ? JSON.parse(fs.readFileSync(metaFile, 'utf8'))
-        : null;
-
-      const sameVersion = installedVersion === version;
-      const sameProfile = !profileHash || installedMeta?.profileHash === profileHash;
-
-      if (sameVersion && sameProfile) {
-        log.info(`Already present: ${name}@${version}${profileHash ? ` [${installedMeta?.profileHash}]` : ''} — skipping`);
-        lockEntries.set(name, {
-          version,
-          profileHash:   installedMeta?.profileHash   ?? null,
-          contentSha256: installedMeta?.contentSha256 ?? null,
-          gitSha:        installedMeta?.gitSha        ?? null,
-          resolvedFrom:  installedMeta?.resolvedFrom  ?? 'cached',
-          ...(options ? { options } : {}),
-        });
-        continue;
-      }
-      if (!sameVersion) {
-        log.info(`Version changed: ${name} ${installedVersion} → ${version}, re-downloading`);
+      if (buildMode === 'always') {
+        log.info(`--build=always: removing existing ${name}@${version} to force source-build`);
+        fs.rmSync(extractDir, { recursive: true, force: true });
       } else {
-        log.info(`Profile changed for ${name}@${version}, re-downloading`);
+        const installedVersion = fs.existsSync(versionFile)
+          ? fs.readFileSync(versionFile, 'utf8').trim()
+          : null;
+        const installedMeta = fs.existsSync(metaFile)
+          ? JSON.parse(fs.readFileSync(metaFile, 'utf8'))
+          : null;
+
+        const sameVersion = installedVersion === version;
+        const sameProfile = !profileHash || installedMeta?.profileHash === profileHash;
+
+        if (sameVersion && sameProfile) {
+          log.info(`Already present: ${name}@${version}${profileHash ? ` [${installedMeta?.profileHash}]` : ''} — skipping`);
+          lockEntries.set(name, {
+            version,
+            profileHash:   installedMeta?.profileHash   ?? null,
+            contentSha256: installedMeta?.contentSha256 ?? null,
+            gitSha:        installedMeta?.gitSha        ?? null,
+            resolvedFrom:  installedMeta?.resolvedFrom  ?? 'cached',
+            ...(options      ? { options }                   : {}),
+            ...(pinnedSource ? { source: pinnedSource.name } : {}),
+          });
+          continue;
+        }
+        if (!sameVersion) {
+          log.info(`Version changed: ${name} ${installedVersion} → ${version}, re-downloading`);
+        } else {
+          log.info(`Profile changed for ${name}@${version}, re-downloading`);
+        }
+        fs.rmSync(extractDir, { recursive: true, force: true });
       }
-      fs.rmSync(extractDir, { recursive: true, force: true });
     }
 
     log.info(`Downloading: ${name}@${version}`);
@@ -439,26 +427,38 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
 
     // ── Try v2 exact ────────────────────────────────────────────────────────
     if (profileHash && profile) {
-      const v2 = await tryV2Exact(
-        { name, version, profileHash },
-        packageSources,
-        destZipPath,
-        timeoutMs,
-        { awsProfile, token },
-      );
+      // --build=always skips every registry-binary path (exact match, compat
+      // match) and goes straight to source-build. Fetch just the versions
+      // index so source-build can find gitRepo/gitSha. EVALUATION.md F9.
+      const v2 = (buildMode === 'always')
+        ? await findV2Index(
+            { name, version },
+            depSources,
+            { awsProfile, token },
+          )
+        : await tryV2Exact(
+            { name, version, profileHash },
+            depSources,
+            destZipPath,
+            timeoutMs,
+            { awsProfile, token },
+          );
 
       if (v2.found) {
         downloadResult = v2.result;
         resolvedFrom   = 'v2';
       } else if (v2.indexFoundInSource) {
-        // v2 knows this package but no exact profile match. Do NOT fall back
-        // to v1 — that would silently accept a binary with different build
-        // settings. Try declarative compatibility first (phase 2), then the
-        // deprecated env-var escape hatch, then fail strictly.
+        // v2 knows this package but no exact profile match (or --build=always
+        // forced the path here). Do NOT fall back to v1 — that would silently
+        // accept a binary with different build settings. Try declarative
+        // compatibility first (phase 2) unless always-mode, then source-build
+        // when --build=missing|always, then fail strictly.
         skipV1Fallback = true;
 
         // ── Phase 2: declarative per-package compatibility ─────────────────
-        const compatResult = await findCompatibleBuild({
+        // Skip under --build=always: the whole point of that flag is to
+        // produce a fresh source-build, not to accept a registry binary.
+        const compatResult = (buildMode === 'always') ? null : await findCompatibleBuild({
           name, version,
           consumerProfile:  profile,
           consumerOptions:  options,
@@ -490,8 +490,8 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
           }
         }
 
-        // ── Phase 3: source-build when `--build=missing` is active ─────────
-        if (!downloadResult && buildMode === 'missing') {
+        // ── Phase 3: source-build when `--build=missing` or `--build=always` ──
+        if (!downloadResult && (buildMode === 'missing' || buildMode === 'always')) {
           const sourceInfo = v2.versionsIndex?.versions?.[version]?.source;
           if (sourceInfo?.gitRepo && sourceInfo?.gitSha) {
             try {
@@ -531,33 +531,16 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
           }
         }
 
-        // ── Deprecated escape hatch: WYVRNPM_ALLOW_LOOSE_COMPAT=1 ──────────
-        if (!downloadResult && looseCompatAllowed) {
-          const compat = await tryV2Compat(
-            { name, version, profile },
-            v2.versionsIndex,
-            v2.indexFoundInSource,
-            destZipPath,
-            timeoutMs,
-            { awsProfile, token },
-          );
-          if (compat) {
-            downloadResult = compat;
-            resolvedFrom   = 'v2-compat-deprecated';
-          }
-        }
-
         if (!downloadResult) {
           log.error(buildStrictMissMessage({
             name, version, profileHash,
             availableProfiles: v2.availableProfiles,
             buildMode,
-            loose: looseCompatAllowed,
           }));
           lockEntries.set(name, {
             version,
             profileHash,
-            resolvedFrom: buildMode === 'missing' ? 'source-build-failed' : 'no-exact-match',
+            resolvedFrom: (buildMode === 'missing' || buildMode === 'always') ? 'source-build-failed' : 'no-exact-match',
             availableProfiles: v2.availableProfiles,
           });
           continue;
@@ -568,7 +551,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
 
     // ── Fall back to v1 ─────────────────────────────────────────────────────
     if (!downloadResult && !skipV1Fallback) {
-      const ok = await tryDownloadFromSources(name, version, packageSources, platform, httpClient, timeoutMs, destZipPath);
+      const ok = await tryDownloadFromSources(name, version, depSources, platform, httpClient, timeoutMs, destZipPath);
       if (!ok) {
         log.warn(`package ${name}@${version} was not found in any configured source`);
         lockEntries.set(name, { version, resolvedFrom: 'not-found' });
@@ -631,7 +614,12 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
         profileHash:   downloadResult?.profileHash   ?? null,
         contentSha256: downloadResult?.contentSha256 ?? null,
         gitSha:        downloadResult?.gitSha        ?? null,
-        ...(options ? { options } : {}),
+        ...(options      ? { options }                        : {}),
+        // S4: record the pinned source name on the lock entry so a
+        // reviewer reading wyvrn.lock can confirm the artefact came
+        // from the declared source. Absent on non-pinned deps so
+        // pre-S4 lockfiles remain byte-identical.
+        ...(pinnedSource ? { source: pinnedSource.name }      : {}),
       });
 
       // ── Upload freshly source-built artefact back to the registry ────────