wyvrnpm 2.10.2 → 2.12.2

package/src/conf/index.js

@@ -1,391 +1,415 @@
-'use strict';
-
-// Non-ABI build-time configuration — the `conf` system (PLAN-CONF.md).
-//
-// `conf` is the sibling of `options` with the opposite hashing
-// property: options fold into `profileHash` (ABI-affecting), conf
-// never does (build-time knobs). See plan §2 for the rationale.
-//
-// This module is the pure core. It parses the four layers
-// (CLI, `wyvrn.local.json`, named profile `[conf]`, recipe
-// `wyvrn.json`), merges them with per-leaf precedence, and produces
-// a flat `{ "namespace.leaf": value }` map ready for each sink to
-// consume. It does NOT know about CMake, filesystems beyond reading
-// a given JSON file, or any command — those live one level up in
-// src/commands/* and src/toolchain/*.
-
-const fs   = require('fs');
-const path = require('path');
-
-const { validateFlatConfKeys } = require('./namespaces');
-
-const LOCAL_OVERLAY_FILENAME = 'wyvrn.local.json';
-
-// Per plan §4.5 "Strict top-level allow-list". Phase-1 accepts only
-// `{ conf }` at the top level of wyvrn.local.json. Adding
-// dependencies/options/etc. to this set is deliberate and plan-2
-// territory.
-const LOCAL_OVERLAY_ALLOWED_TOP_KEYS = new Set(['conf']);
-
-// ---------------------------------------------------------------------------
-// Value normalisation
-// ---------------------------------------------------------------------------
-
-/**
- * Normalise a single leaf VALUE into the string CMake (or whichever
- * sink consumes it) expects. JSON `true`/`false` become `"ON"`/`"OFF"`;
- * numbers are stringified; strings pass through. Arrays / objects /
- * null at a leaf position are a hard error — those live at branch
- * positions, not leaves.
- *
- * CLI values arrive as strings and are passed through verbatim.
- *
- * @param {unknown} value
- * @param {string}  keyForError
- * @returns {string}
- */
-function normalizeLeafValue(value, keyForError) {
-  if (value === true)  return 'ON';
-  if (value === false) return 'OFF';
-  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
-  if (typeof value === 'string') return value;
-  throw new Error(
-    `conf value for ${JSON.stringify(keyForError)} must be a string, ` +
-    `number, or boolean — got ${JSON.stringify(value)}`,
-  );
-}
-
-/**
- * Flatten a nested conf object (recipe/local form) into a flat
- * `{ "ns.leaf": stringValue }` map. Keys are joined with `.`. The
- * recursion stops at any non-object (strings, numbers, booleans) —
- * those are leaves.
- *
- * Throws on:
- *   - null at a leaf position
- *   - arrays anywhere (arrays are not meaningful for cmake cache vars
- *     and leaving them as "maybe later" invites footguns)
- *   - objects whose keys contain `.` (would clash with our separator)
- *
- * @param {object} nested
- * @param {string} [prefix]
- * @param {Record<string, string>} [out]
- * @returns {Record<string, string>}
- */
-function flattenConf(nested, prefix = '', out = {}) {
-  if (nested === null || typeof nested !== 'object') {
-    throw new Error(
-      `conf block must be an object — got ${JSON.stringify(nested)} at ` +
-      `${prefix || '<root>'}`,
-    );
-  }
-  if (Array.isArray(nested)) {
-    throw new Error(`conf block must be an object, not an array — at ${prefix || '<root>'}`);
-  }
-
-  for (const [rawKey, value] of Object.entries(nested)) {
-    if (rawKey.includes('.')) {
-      throw new Error(
-        `conf key segment ${JSON.stringify(rawKey)} must not contain a period — ` +
-        `use nested objects or the flat "namespace.leaf" form, not both`,
-      );
-    }
-    const fullKey = prefix ? `${prefix}.${rawKey}` : rawKey;
-
-    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
-      flattenConf(value, fullKey, out);
-    } else {
-      out[fullKey] = normalizeLeafValue(value, fullKey);
-    }
-  }
-  return out;
-}
-
-/**
- * Re-expand a flat `{ "ns.leaf": value }` map back into nested form,
- * for emitting into JSON manifests / lockfiles / payloads in the same
- * shape authors author with. Values round-trip as strings (conf
- * values are always strings post-normalisation).
- *
- * @param {Record<string, string>} flat
- * @returns {object}
- */
-function unflattenConf(flat) {
-  const root = {};
-  for (const [key, value] of Object.entries(flat)) {
-    const parts = key.split('.');
-    let node = root;
-    for (let i = 0; i < parts.length - 1; i++) {
-      const seg = parts[i];
-      if (node[seg] === undefined || typeof node[seg] !== 'object') {
-        node[seg] = {};
-      }
-      node = node[seg];
-    }
-    node[parts[parts.length - 1]] = value;
-  }
-  return root;
-}
-
-// ---------------------------------------------------------------------------
-// CLI parsing
-// ---------------------------------------------------------------------------
-
-/**
- * Parse an array of `--conf KEY=VALUE` strings (yargs delivers
- * `argv.conf` when the option is registered as `array: true`) into a
- * flat map. See plan §4.4 for semantics:
- *
- *   KEY=VALUE  → set the key to VALUE verbatim (string).
- *   KEY        → alias for KEY=true (matches CMake's -D convention).
- *   KEY=       → unset (remove the key from lower layers on merge).
- *
- * Returns two maps — set values and unset keys — so the merger can
- * treat the latter specially.
- *
- * @param {string[] | undefined} rawArgs
- * @returns {{ sets: Record<string,string>, unsets: Set<string> }}
- */
-function parseCliConf(rawArgs) {
-  const sets   = {};
-  const unsets = new Set();
-
-  if (!rawArgs || rawArgs.length === 0) {
-    return { sets, unsets };
-  }
-
-  for (const arg of rawArgs) {
-    if (typeof arg !== 'string') {
-      throw new Error(`--conf expects KEY=VALUE string; got ${JSON.stringify(arg)}`);
-    }
-    const eqIdx = arg.indexOf('=');
-    if (eqIdx < 0) {
-      // Bare `KEY` → KEY=true (normalised to "ON").
-      const key = arg.trim();
-      if (key.length === 0) {
-        throw new Error('--conf was given an empty key');
-      }
-      sets[key] = 'ON';
-    } else {
-      const key   = arg.slice(0, eqIdx).trim();
-      const value = arg.slice(eqIdx + 1);
-      if (key.length === 0) {
-        throw new Error(`--conf ${JSON.stringify(arg)} has an empty key`);
-      }
-      if (value.length === 0) {
-        // KEY= → unset. Distinguish from KEY="" which callers can
-        // achieve by quoting the value; here the shell has already
-        // stripped the quotes, so an empty string past the `=` means
-        // "clear any inherited value for this key."
-        unsets.add(key);
-      } else {
-        sets[key] = value;
-      }
-    }
-  }
-
-  return { sets, unsets };
-}
-
-// ---------------------------------------------------------------------------
-// Local-overlay file
-// ---------------------------------------------------------------------------
-
-/**
- * Read and validate `wyvrn.local.json` at the given project root.
- * Returns the parsed `conf` block as a flat map, or an empty map when
- * the file is absent.
- *
- * Enforces plan §4.5: the only top-level key this file may carry in
- * phase 1 is `conf`; anything else is a hard error (not a warning).
- *
- * @param {string} rootDir
- * @returns {{ flat: Record<string,string>, path: string|null }}
- */
-function readLocalOverlay(rootDir) {
-  const p = path.join(rootDir, LOCAL_OVERLAY_FILENAME);
-  if (!fs.existsSync(p)) return { flat: {}, path: null };
-
-  let raw;
-  try {
-    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch (err) {
-    throw new Error(`cannot parse ${LOCAL_OVERLAY_FILENAME}: ${err.message}`);
-  }
-  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
-    throw new Error(`${LOCAL_OVERLAY_FILENAME} must contain a JSON object at the top level`);
-  }
-
-  for (const key of Object.keys(raw)) {
-    if (!LOCAL_OVERLAY_ALLOWED_TOP_KEYS.has(key)) {
-      const allowed = [...LOCAL_OVERLAY_ALLOWED_TOP_KEYS].join(', ');
-      throw new Error(
-        `${LOCAL_OVERLAY_FILENAME}: unknown top-level key ${JSON.stringify(key)} — ` +
-        `phase-1 allow-list: [${allowed}]. ` +
-        `If you meant to override dependencies or options, that is reserved ` +
-        `for a future phase; see claude/PLAN-CONF.md §4.5.`,
-      );
-    }
-  }
-
-  const confBlock = raw.conf ?? {};
-  const flat = flattenConf(confBlock);
-  validateFlatConfKeys(flat);
-  return { flat, path: p };
-}
-
-// ---------------------------------------------------------------------------
-// Recipe extraction
-// ---------------------------------------------------------------------------
-
-/**
- * Pull the `conf` block out of an already-loaded recipe manifest and
- * flatten it. A missing block is an empty map.
- *
- * Validation runs against the phase-1 allow-list; if a recipe declares
- * a namespace we don't support yet, the install fails with a clear
- * error rather than silently dropping the config.
- *
- * @param {object} manifest
- * @returns {Record<string,string>}
- */
-function readRecipeConf(manifest) {
-  const block = manifest?.conf ?? null;
-  if (block === null || block === undefined) return {};
-  const flat = flattenConf(block);
-  validateFlatConfKeys(flat);
-  return flat;
-}
-
-// ---------------------------------------------------------------------------
-// Profile extraction
-// ---------------------------------------------------------------------------
-
-/**
- * Pull the optional `conf` block out of a loaded named profile JSON
- * (see src/profile.js) and flatten it. A missing block is an empty
- * map — profiles without `conf` round-trip byte-identically to
- * pre-phase-2 behaviour.
- *
- * Validation runs against the phase-1 allow-list; an unknown
- * namespace in a profile fails fast rather than silently dropping
- * the config (CLAUDE.md §2 principle 8).
- *
- * @param {object|null|undefined} profile
- * @returns {Record<string,string>}
- */
-function readProfileConf(profile) {
-  const block = profile?.conf ?? null;
-  if (block === null || block === undefined) return {};
-  const flat = flattenConf(block);
-  validateFlatConfKeys(flat);
-  return flat;
-}
-
-// ---------------------------------------------------------------------------
-// Merge
-// ---------------------------------------------------------------------------
-
-/**
- * Merge the four layers with plan §4.2 precedence (post phase-2):
- *
- *   CLI unsets   — remove named keys from below.
- *   CLI sets     — highest wins.
- *   local        — overrides profile.
- *   profile      — overrides recipe (team-shared team defaults).
- *   recipe       — base defaults.
- *
- * Per-leaf override, not per-branch replace — so CLI setting only
- * cmake.cache.FOO does not disturb a recipe's cmake.cache.BAR.
- *
- * The `profileFlat` parameter is optional. Pre-phase-2 callers that
- * pass only three layers (recipe, local, cli) still work — profile
- * defaults to an empty map, preserving the three-layer semantics
- * exactly.
- *
- * @param {Record<string,string>} recipeFlat
- * @param {Record<string,string>} localFlat
- * @param {{ sets: Record<string,string>, unsets: Set<string> }} cli
- * @param {Record<string,string>} [profileFlat]
- * @returns {Record<string,string>}
- */
-function mergeConfLayers(recipeFlat, localFlat, cli, profileFlat = {}) {
-  const out = { ...recipeFlat, ...profileFlat, ...localFlat, ...cli.sets };
-  for (const k of cli.unsets) delete out[k];
-  validateFlatConfKeys(out);
-  return out;
-}
-
-/**
- * Convenience: do the whole four-layer resolution at once. Most
- * callers want this. Individual layer helpers are exported for tests.
- *
- * The `profile` argument is optional. Callers that don't have a
- * resolved profile to hand (e.g. the legacy three-layer call sites in
- * `publish`, which intentionally ignore the profile tier so published
- * artefacts aren't skewed by dev machines) pass nothing and get the
- * three-layer merge (CLI > local > recipe).
- *
- * @param {object} args
- * @param {object} [args.manifest]
- * @param {string} args.rootDir
- * @param {string[]} [args.cliConf]
- * @param {object} [args.profile]  Resolved named profile JSON (may carry .conf).
- * @returns {{
- *   flat:             Record<string,string>,
- *   recipeFlat:       Record<string,string>,
- *   profileFlat:      Record<string,string>,
- *   localFlat:        Record<string,string>,
- *   cli:              { sets: Record<string,string>, unsets: Set<string> },
- *   localOverlayPath: string | null,
- * }}
- */
-function resolveEffectiveConf({ manifest, rootDir, cliConf, profile }) {
-  const recipeFlat  = readRecipeConf(manifest);
-  const profileFlat = readProfileConf(profile);
-  const { flat: localFlat, path: localOverlayPath } = readLocalOverlay(rootDir);
-  const cli = parseCliConf(cliConf);
-  const flat = mergeConfLayers(recipeFlat, localFlat, cli, profileFlat);
-  return { flat, recipeFlat, profileFlat, localFlat, cli, localOverlayPath };
-}
-
-/**
- * Extract only the `cmake.cache.*` portion of a flat conf map as
- * `{ VARNAME: stringValue }` — the shape
- * `src/toolchain/presets.js` wants for `cacheVariables`. Stable
- * alphabetical key order so preset diffs are deterministic.
- *
- * @param {Record<string,string>} flatConf
- * @returns {Record<string,string>}
- */
-function cmakeCacheVariables(flatConf) {
-  const out = {};
-  const prefix = 'cmake.cache.';
-  const keys = Object.keys(flatConf).filter((k) => k.startsWith(prefix)).sort();
-  for (const k of keys) {
-    out[k.slice(prefix.length)] = flatConf[k];
-  }
-  return out;
-}
-
-module.exports = {
-  // High-level
-  resolveEffectiveConf,
-
-  // Per-layer
-  parseCliConf,
-  readLocalOverlay,
-  readRecipeConf,
-  readProfileConf,
-  mergeConfLayers,
-
-  // Shape transforms
-  flattenConf,
-  unflattenConf,
-  normalizeLeafValue,
-  cmakeCacheVariables,
-
-  // Constants (exported for tests + integration)
-  LOCAL_OVERLAY_FILENAME,
-  LOCAL_OVERLAY_ALLOWED_TOP_KEYS,
-};
+'use strict';
+
+// Non-ABI build-time configuration — the `conf` system (PLAN-CONF.md).
+//
+// `conf` is the sibling of `options` with the opposite hashing
+// property: options fold into `profileHash` (ABI-affecting), conf
+// never does (build-time knobs). See plan §2 for the rationale.
+//
+// This module is the pure core. It parses the four layers
+// (CLI, `wyvrn.local.json`, named profile `[conf]`, recipe
+// `wyvrn.json`), merges them with per-leaf precedence, and produces
+// a flat `{ "namespace.leaf": value }` map ready for each sink to
+// consume. It does NOT know about CMake, filesystems beyond reading
+// a given JSON file, or any command — those live one level up in
+// src/commands/* and src/toolchain/*.
+
+const fs   = require('fs');
+const path = require('path');
+
+const { validateFlatConfKeys } = require('./namespaces');
+
+const LOCAL_OVERLAY_FILENAME = 'wyvrn.local.json';
+
+// Per plan §4.5 "Strict top-level allow-list". Two top-level keys
+// today:
+//   - `conf`           — non-ABI build-time knobs (PLAN-CONF.md).
+//   - `binaryDirRoot`  — dev-local override of the preset's build
+//                        subdir (sibling channel to --build-dir on
+//                        install/build). See src/binary-dir.js.
+// Adding dependencies/options/etc. is plan-2 territory.
+const LOCAL_OVERLAY_ALLOWED_TOP_KEYS = new Set(['conf', 'binaryDirRoot']);
+
+// ---------------------------------------------------------------------------
+// Value normalisation
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalise a single leaf VALUE into the string CMake (or whichever
+ * sink consumes it) expects. JSON `true`/`false` become `"ON"`/`"OFF"`;
+ * numbers are stringified; strings pass through. Arrays / objects /
+ * null at a leaf position are a hard error — those live at branch
+ * positions, not leaves.
+ *
+ * CLI values arrive as strings and are passed through verbatim.
+ *
+ * @param {unknown} value
+ * @param {string}  keyForError
+ * @returns {string}
+ */
+function normalizeLeafValue(value, keyForError) {
+  if (value === true)  return 'ON';
+  if (value === false) return 'OFF';
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value === 'string') return value;
+  throw new Error(
+    `conf value for ${JSON.stringify(keyForError)} must be a string, ` +
+    `number, or boolean — got ${JSON.stringify(value)}`,
+  );
+}
+
+/**
+ * Flatten a nested conf object (recipe/local form) into a flat
+ * `{ "ns.leaf": stringValue }` map. Keys are joined with `.`. The
+ * recursion stops at any non-object (strings, numbers, booleans) —
+ * those are leaves.
+ *
+ * Throws on:
+ *   - null at a leaf position
+ *   - arrays anywhere (arrays are not meaningful for cmake cache vars
+ *     and leaving them as "maybe later" invites footguns)
+ *   - objects whose keys contain `.` (would clash with our separator)
+ *
+ * @param {object} nested
+ * @param {string} [prefix]
+ * @param {Record<string, string>} [out]
+ * @returns {Record<string, string>}
+ */
+function flattenConf(nested, prefix = '', out = {}) {
+  if (nested === null || typeof nested !== 'object') {
+    throw new Error(
+      `conf block must be an object — got ${JSON.stringify(nested)} at ` +
+      `${prefix || '<root>'}`,
+    );
+  }
+  if (Array.isArray(nested)) {
+    throw new Error(`conf block must be an object, not an array — at ${prefix || '<root>'}`);
+  }
+
+  for (const [rawKey, value] of Object.entries(nested)) {
+    if (rawKey.includes('.')) {
+      throw new Error(
+        `conf key segment ${JSON.stringify(rawKey)} must not contain a period — ` +
+        `use nested objects or the flat "namespace.leaf" form, not both`,
+      );
+    }
+    const fullKey = prefix ? `${prefix}.${rawKey}` : rawKey;
+
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      flattenConf(value, fullKey, out);
+    } else {
+      out[fullKey] = normalizeLeafValue(value, fullKey);
+    }
+  }
+  return out;
+}
+
+/**
+ * Re-expand a flat `{ "ns.leaf": value }` map back into nested form,
+ * for emitting into JSON manifests / lockfiles / payloads in the same
+ * shape authors author with. Values round-trip as strings (conf
+ * values are always strings post-normalisation).
+ *
+ * @param {Record<string, string>} flat
+ * @returns {object}
+ */
+function unflattenConf(flat) {
+  const root = {};
+  for (const [key, value] of Object.entries(flat)) {
+    const parts = key.split('.');
+    let node = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const seg = parts[i];
+      if (node[seg] === undefined || typeof node[seg] !== 'object') {
+        node[seg] = {};
+      }
+      node = node[seg];
+    }
+    node[parts[parts.length - 1]] = value;
+  }
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// CLI parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse an array of `--conf KEY=VALUE` strings (yargs delivers
+ * `argv.conf` when the option is registered as `array: true`) into a
+ * flat map. See plan §4.4 for semantics:
+ *
+ *   KEY=VALUE  → set the key to VALUE verbatim (string).
+ *   KEY        → alias for KEY=true (matches CMake's -D convention).
+ *   KEY=       → unset (remove the key from lower layers on merge).
+ *
+ * Returns two maps — set values and unset keys — so the merger can
+ * treat the latter specially.
+ *
+ * @param {string[] | undefined} rawArgs
+ * @returns {{ sets: Record<string,string>, unsets: Set<string> }}
+ */
+function parseCliConf(rawArgs) {
+  const sets   = {};
+  const unsets = new Set();
+
+  if (!rawArgs || rawArgs.length === 0) {
+    return { sets, unsets };
+  }
+
+  for (const arg of rawArgs) {
+    if (typeof arg !== 'string') {
+      throw new Error(`--conf expects KEY=VALUE string; got ${JSON.stringify(arg)}`);
+    }
+    const eqIdx = arg.indexOf('=');
+    if (eqIdx < 0) {
+      // Bare `KEY` → KEY=true (normalised to "ON").
+      const key = arg.trim();
+      if (key.length === 0) {
+        throw new Error('--conf was given an empty key');
+      }
+      sets[key] = 'ON';
+    } else {
+      const key   = arg.slice(0, eqIdx).trim();
+      const value = arg.slice(eqIdx + 1);
+      if (key.length === 0) {
+        throw new Error(`--conf ${JSON.stringify(arg)} has an empty key`);
+      }
+      if (value.length === 0) {
+        // KEY= → unset. Distinguish from KEY="" which callers can
+        // achieve by quoting the value; here the shell has already
+        // stripped the quotes, so an empty string past the `=` means
+        // "clear any inherited value for this key."
+        unsets.add(key);
+      } else {
+        sets[key] = value;
+      }
+    }
+  }
+
+  return { sets, unsets };
+}
+
+// ---------------------------------------------------------------------------
+// Local-overlay file
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and validate `wyvrn.local.json` at the given project root.
+ * Returns the parsed `conf` block as a flat map, or an empty map when
+ * the file is absent.
+ *
+ * Enforces plan §4.5: the only top-level key this file may carry in
+ * phase 1 is `conf`; anything else is a hard error (not a warning).
+ *
+ * @param {string} rootDir
+ * @returns {{ flat: Record<string,string>, path: string|null, binaryDirRoot: string|null }}
+ */
+function readLocalOverlay(rootDir) {
+  const p = path.join(rootDir, LOCAL_OVERLAY_FILENAME);
+  if (!fs.existsSync(p)) return { flat: {}, path: null, binaryDirRoot: null };
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (err) {
+    throw new Error(`cannot parse ${LOCAL_OVERLAY_FILENAME}: ${err.message}`);
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${LOCAL_OVERLAY_FILENAME} must contain a JSON object at the top level`);
+  }
+
+  for (const key of Object.keys(raw)) {
+    if (!LOCAL_OVERLAY_ALLOWED_TOP_KEYS.has(key)) {
+      const allowed = [...LOCAL_OVERLAY_ALLOWED_TOP_KEYS].join(', ');
+      throw new Error(
+        `${LOCAL_OVERLAY_FILENAME}: unknown top-level key ${JSON.stringify(key)} — ` +
+        `allow-list: [${allowed}]. ` +
+        `If you meant to override dependencies or options, that is reserved ` +
+        `for a future phase; see claude/PLAN-CONF.md §4.5.`,
+      );
+    }
+  }
+
+  const confBlock = raw.conf ?? {};
+  const flat = flattenConf(confBlock);
+  validateFlatConfKeys(flat);
+
+  // `binaryDirRoot` is only validated for type/shape here; the actual
+  // path-syntax check (no abs, no `..`, etc.) lives in src/binary-dir.js
+  // which has the canonical ruleset. Returning the raw string keeps the
+  // two modules decoupled.
+  const binaryDirRoot = Object.prototype.hasOwnProperty.call(raw, 'binaryDirRoot')
+    ? raw.binaryDirRoot
+    : null;
+
+  return { flat, path: p, binaryDirRoot };
+}
+
+// ---------------------------------------------------------------------------
+// Recipe extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull the `conf` block out of an already-loaded recipe manifest and
+ * flatten it. A missing block is an empty map.
+ *
+ * Validation runs against the phase-1 allow-list; if a recipe declares
+ * a namespace we don't support yet, the install fails with a clear
+ * error rather than silently dropping the config.
+ *
+ * @param {object} manifest
+ * @returns {Record<string,string>}
+ */
+function readRecipeConf(manifest) {
+  const block = manifest?.conf ?? null;
+  if (block === null || block === undefined) return {};
+  const flat = flattenConf(block);
+  validateFlatConfKeys(flat);
+  return flat;
+}
+
+// ---------------------------------------------------------------------------
+// Profile extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull the optional `conf` block out of a loaded named profile JSON
+ * (see src/profile.js) and flatten it. A missing block is an empty
+ * map — profiles without `conf` round-trip byte-identically to
+ * pre-phase-2 behaviour.
+ *
+ * Validation runs against the phase-1 allow-list; an unknown
+ * namespace in a profile fails fast rather than silently dropping
+ * the config (CLAUDE.md §2 principle 8).
+ *
+ * @param {object|null|undefined} profile
+ * @returns {Record<string,string>}
+ */
+function readProfileConf(profile) {
+  const block = profile?.conf ?? null;
+  if (block === null || block === undefined) return {};
+  const flat = flattenConf(block);
+  validateFlatConfKeys(flat);
+  return flat;
+}
+
+// ---------------------------------------------------------------------------
+// Merge
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge the four layers with plan §4.2 precedence (post phase-2):
+ *
+ *   CLI unsets   — remove named keys from below.
+ *   CLI sets     — highest wins.
+ *   local        — overrides profile.
+ *   profile      — overrides recipe (team-shared team defaults).
+ *   recipe       — base defaults.
+ *
+ * Per-leaf override, not per-branch replace — so CLI setting only
+ * cmake.cache.FOO does not disturb a recipe's cmake.cache.BAR.
+ *
+ * The `profileFlat` parameter is optional. Pre-phase-2 callers that
+ * pass only three layers (recipe, local, cli) still work — profile
+ * defaults to an empty map, preserving the three-layer semantics
+ * exactly.
+ *
+ * @param {Record<string,string>} recipeFlat
+ * @param {Record<string,string>} localFlat
+ * @param {{ sets: Record<string,string>, unsets: Set<string> }} cli
+ * @param {Record<string,string>} [profileFlat]
+ * @returns {Record<string,string>}
+ */
+function mergeConfLayers(recipeFlat, localFlat, cli, profileFlat = {}) {
+  const out = { ...recipeFlat, ...profileFlat, ...localFlat, ...cli.sets };
+  for (const k of cli.unsets) delete out[k];
+  validateFlatConfKeys(out);
+  return out;
+}
+
+/**
+ * Convenience: do the whole four-layer resolution at once. Most
+ * callers want this. Individual layer helpers are exported for tests.
+ *
+ * The `profile` argument is optional. Callers that don't have a
+ * resolved profile to hand (e.g. the legacy three-layer call sites in
+ * `publish`, which intentionally ignore the profile tier so published
+ * artefacts aren't skewed by dev machines) pass nothing and get the
+ * three-layer merge (CLI > local > recipe).
+ *
+ * @param {object} args
+ * @param {object} [args.manifest]
+ * @param {string} args.rootDir
+ * @param {string[]} [args.cliConf]
+ * @param {object} [args.profile]  Resolved named profile JSON (may carry .conf).
+ * @returns {{
+ *   flat:             Record<string,string>,
+ *   recipeFlat:       Record<string,string>,
+ *   profileFlat:      Record<string,string>,
+ *   localFlat:        Record<string,string>,
+ *   cli:              { sets: Record<string,string>, unsets: Set<string> },
+ *   localOverlayPath: string | null,
+ * }}
+ */
+function resolveEffectiveConf({ manifest, rootDir, cliConf, profile }) {
+  const recipeFlat  = readRecipeConf(manifest);
+  const profileFlat = readProfileConf(profile);
+  const overlay = readLocalOverlay(rootDir);
+  const { flat: localFlat, path: localOverlayPath, binaryDirRoot: localBinaryDirRoot } = overlay;
+  const cli = parseCliConf(cliConf);
+  const flat = mergeConfLayers(recipeFlat, localFlat, cli, profileFlat);
+  return {
+    flat,
+    recipeFlat,
+    profileFlat,
+    localFlat,
+    cli,
+    localOverlayPath,
+    // Surfaced so install can route this into src/binary-dir.js without
+    // re-reading the overlay file. Validated downstream — this just
+    // forwards the raw value the user wrote.
+    localBinaryDirRoot,
+  };
+}
+
+/**
+ * Extract only the `cmake.cache.*` portion of a flat conf map as
+ * `{ VARNAME: stringValue }` — the shape
+ * `src/toolchain/presets.js` wants for `cacheVariables`. Stable
+ * alphabetical key order so preset diffs are deterministic.
+ *
+ * @param {Record<string,string>} flatConf
+ * @returns {Record<string,string>}
+ */
+function cmakeCacheVariables(flatConf) {
+  const out = {};
+  const prefix = 'cmake.cache.';
+  const keys = Object.keys(flatConf).filter((k) => k.startsWith(prefix)).sort();
+  for (const k of keys) {
+    out[k.slice(prefix.length)] = flatConf[k];
+  }
+  return out;
+}
+
+module.exports = {
+  // High-level
+  resolveEffectiveConf,
+
+  // Per-layer
+  parseCliConf,
+  readLocalOverlay,
+  readRecipeConf,
+  readProfileConf,
+  mergeConfLayers,
+
+  // Shape transforms
+  flattenConf,
+  unflattenConf,
+  normalizeLeafValue,
+  cmakeCacheVariables,
+
+  // Constants (exported for tests + integration)
+  LOCAL_OVERLAY_FILENAME,
+  LOCAL_OVERLAY_ALLOWED_TOP_KEYS,
+};