@cdxgen/cdxgen 13.0.1 → 13.1.0

package/lib/stages/postgen/introspection/shapeCommand.js

@@ -0,0 +1,304 @@
+/**
+ * Command shaping for remediation actions.
+ *
+ * The remediation catalog authors commands with template variables where the
+ * right value depends on the scanned project: which maven or gradle
+ * executable the repo wraps, which Python manager owns its lock files, which
+ * client npm itself should use. This module substitutes those variables from
+ * a facts object the caller gathered earlier, and names on every shaped
+ * command the detection it relied on, so a reviewer can tell a correct
+ * detection from a lucky default.
+ *
+ * Every function here is pure: the facts object is the only input beyond the
+ * template string, nothing reads the filesystem, and the same facts always
+ * yield the same command. The filesystem reads live in the collector
+ * (`commandFacts.js`).
+ */
+
+/**
+ * Template variables this module substitutes, beside the `{{version}}` and
+ * `{{major}}` placeholders the version cascade fills.
+ *
+ * @type {Readonly<string[]>}
+ */
+export const SHAPE_VARIABLES = Object.freeze([
+  "mvn",
+  "gradle",
+  "pythonManager",
+  "npmClient",
+  "go",
+  "cargo",
+  "composer",
+  "dart",
+  "mix",
+  "cabal",
+]);
+
+/**
+ * Python managers a command can name, with the lock command each catalog
+ * entry pairs the variable with.
+ *
+ * @type {Readonly<string[]>}
+ */
+export const PYTHON_MANAGERS = Object.freeze(["uv", "poetry", "pdm", "pipenv"]);
+
+/**
+ * Project facts one shaping pass consumes. Produced once per run by the
+ * collector; every field is optional so a caller without collector facts
+ * still resolves the fallbacks.
+ *
+ * @typedef {Object} CommandFacts
+ * @property {string} [projectRoot] Directory the facts were gathered from.
+ * @property {"posix"|"windows"} [platform] Platform the command targets; defaults to posix.
+ * @property {Object} [wrappers] Wrapper presence facts, executable-bit included for the platform's script.
+ * @property {boolean} [wrappers.mvnw] ./mvnw exists and is executable.
+ * @property {boolean} [wrappers.mvnwInexecutable] ./mvnw exists but is not executable.
+ * @property {boolean} [wrappers.mvnwCmd] mvnw.cmd exists (Windows variant).
+ * @property {boolean} [wrappers.gradlew] ./gradlew exists and is executable.
+ * @property {boolean} [wrappers.gradlewInexecutable] ./gradlew exists but is not executable.
+ * @property {boolean} [wrappers.gradlewBat] gradlew.bat exists (Windows variant).
+ * @property {boolean} [wrappers.composerPhar] ./composer.phar exists and is executable.
+ * @property {string|undefined} [pythonManager] The Python manager in play.
+ * @property {string[]} [pythonManagerCandidates] Every manager detected, when two or more compete.
+ * @property {string} [npmClient] The npm client the project names or locks.
+ */
+
+/** Wrapper executable the POSIX {{mvn}} variable resolves to. */
+const MAVEN_WRAPPER_POSIX = "./mvnw";
+/** Wrapper executable the Windows {{mvn}} variable resolves to. */
+const MAVEN_WRAPPER_WINDOWS = "mvnw.cmd";
+/** Wrapper executable the POSIX {{gradle}} variable resolves to. */
+const GRADLE_WRAPPER_POSIX = "./gradlew";
+/** Wrapper executable the Windows {{gradle}} variable resolves to. */
+const GRADLE_WRAPPER_WINDOWS = "gradlew.bat";
+/** Wrapper executable the POSIX {{composer}} variable resolves to. */
+const COMPOSER_PHAR_POSIX = "./composer.phar";
+
+/**
+ * The facts for the platform one command variant targets: the collector's
+ * platform fact describes the run, while a Windows command string needs
+ * Windows resolution even on a POSIX run.
+ *
+ * @param {CommandFacts} facts Gathered facts.
+ * @param {boolean} windows True for a Windows command variant.
+ * @returns {CommandFacts} Facts pinned to the requested platform.
+ */
+function factsForPlatform(facts, windows) {
+  const platform = windows
+    ? "windows"
+    : facts?.platform === "windows"
+      ? "windows"
+      : "posix";
+  return { ...(facts || {}), platform };
+}
+
+/**
+ * Resolve the `{{mvn}}` variable for one platform: the project's wrapper
+ * when it is present and usable, the plain executable otherwise.
+ *
+ * @param {CommandFacts} facts Platform-pinned facts.
+ * @returns {{value: string, shapedBy: string|undefined}} Substitute and the detection behind it, when there was one.
+ */
+function resolveMaven(facts) {
+  const windows = facts.platform === "windows";
+  const wrapper = windows ? facts?.wrappers?.mvnwCmd : facts?.wrappers?.mvnw;
+  if (wrapper) {
+    return {
+      value: windows ? MAVEN_WRAPPER_WINDOWS : MAVEN_WRAPPER_POSIX,
+      shapedBy: `wrapper:${windows ? MAVEN_WRAPPER_WINDOWS : MAVEN_WRAPPER_POSIX}`,
+    };
+  }
+  if (!windows && facts?.wrappers?.mvnwInexecutable) {
+    return {
+      value: "mvn",
+      shapedBy: `wrapper-not-executable:${MAVEN_WRAPPER_POSIX}`,
+    };
+  }
+  return { value: "mvn", shapedBy: undefined };
+}
+
+/**
+ * Resolve the `{{gradle}}` variable for one platform: the project's wrapper
+ * when it is present and usable, the plain executable otherwise.
+ *
+ * @param {CommandFacts} facts Platform-pinned facts.
+ * @returns {{value: string, shapedBy: string|undefined}} Substitute and the detection behind it, when there was one.
+ */
+function resolveGradle(facts) {
+  const windows = facts.platform === "windows";
+  const wrapper = windows
+    ? facts?.wrappers?.gradlewBat
+    : facts?.wrappers?.gradlew;
+  if (wrapper) {
+    return {
+      value: windows ? GRADLE_WRAPPER_WINDOWS : GRADLE_WRAPPER_POSIX,
+      shapedBy: `wrapper:${windows ? GRADLE_WRAPPER_WINDOWS : GRADLE_WRAPPER_POSIX}`,
+    };
+  }
+  if (!windows && facts?.wrappers?.gradlewInexecutable) {
+    return {
+      value: "gradle",
+      shapedBy: `wrapper-not-executable:${GRADLE_WRAPPER_POSIX}`,
+    };
+  }
+  return { value: "gradle", shapedBy: undefined };
+}
+
+/**
+ * Resolve the `{{pythonManager}}` variable: the manager the collector
+ * detected, left unresolved when two managers compete and the project does
+ * not settle the question, or when none was detected.
+ *
+ * @param {CommandFacts} facts Platform-pinned facts.
+ * @returns {{value: string|undefined, shapedBy: string|undefined, shapedNote: string|undefined}} Substitute, the detection behind it, and the question for the agent when detection could not answer.
+ */
+function resolvePythonManager(facts) {
+  const manager = facts?.pythonManager;
+  if (manager) {
+    return {
+      value: manager,
+      shapedBy: `manager:${manager}`,
+      shapedNote: undefined,
+    };
+  }
+  const candidates = Array.isArray(facts?.pythonManagerCandidates)
+    ? facts.pythonManagerCandidates.filter(Boolean)
+    : [];
+  if (candidates.length > 1) {
+    return {
+      value: undefined,
+      shapedBy: "manager:ambiguous",
+      shapedNote: `this project carries the lock files of ${candidates.join(" and ")}; confirm which one manages it before locking`,
+    };
+  }
+  return {
+    value: undefined,
+    shapedBy: "manager:unresolved",
+    shapedNote: undefined,
+  };
+}
+
+/**
+ * Resolve the `{{npmClient}}` variable: the client the project names or
+ * locks, npm when nothing says otherwise.
+ *
+ * @param {CommandFacts} facts Platform-pinned facts.
+ * @returns {{value: string, shapedBy: string|undefined}} Substitute and the detection behind it, when there was one.
+ */
+function resolveNpmClient(facts) {
+  const client = facts?.npmClient || "npm";
+  return {
+    value: client,
+    shapedBy: client === "npm" ? undefined : `npm-client:${client}`,
+  };
+}
+
+/**
+ * Resolve the `{{composer}}` variable: the project's local composer.phar when
+ * it is present and usable, the plain executable otherwise.
+ *
+ * @param {CommandFacts} facts Platform-pinned facts.
+ * @returns {{value: string, shapedBy: string|undefined}} Substitute and the detection behind it, when there was one.
+ */
+function resolveComposer(facts) {
+  const windows = facts.platform === "windows";
+  if (!windows && facts?.wrappers?.composerPhar) {
+    return {
+      value: COMPOSER_PHAR_POSIX,
+      shapedBy: `wrapper:${COMPOSER_PHAR_POSIX}`,
+    };
+  }
+  return { value: "composer", shapedBy: undefined };
+}
+
+/**
+ * Resolve a tool variable whose executable no wrapper or version manager in
+ * the facts overrides: the plain executable name.
+ *
+ * @param {string} executable The tool's executable name.
+ * @returns {(facts: CommandFacts) => {value: string, shapedBy: string|undefined}} Resolver for that tool's variable.
+ */
+function resolvePlainExecutable(executable) {
+  return () => ({ value: executable, shapedBy: undefined });
+}
+
+const VARIABLE_RESOLVERS = {
+  mvn: resolveMaven,
+  gradle: resolveGradle,
+  pythonManager: resolvePythonManager,
+  npmClient: resolveNpmClient,
+  go: resolvePlainExecutable("go"),
+  cargo: resolvePlainExecutable("cargo"),
+  composer: resolveComposer,
+  dart: resolvePlainExecutable("dart"),
+  mix: resolvePlainExecutable("mix"),
+  cabal: resolvePlainExecutable("cabal"),
+};
+
+/**
+ * Substitute one template variable, leaving an unresolved `{{pythonManager}}`
+ * verbatim so the command stays an honest question.
+ *
+ * @param {string} command Command carrying the variable.
+ * @param {string} variable Variable name without braces.
+ * @param {CommandFacts} facts Platform-pinned facts.
+ * @returns {{command: string, shapedBy: string|undefined, shapedNote: string|undefined}} Command after substitution.
+ */
+function substituteVariable(command, variable, facts) {
+  const placeholder = `{{${variable}}}`;
+  if (!command.includes(placeholder)) {
+    return { command, shapedBy: undefined, shapedNote: undefined };
+  }
+  const resolved = VARIABLE_RESOLVERS[variable](facts);
+  if (!resolved.value) {
+    return {
+      command,
+      shapedBy: resolved.shapedBy,
+      shapedNote: resolved.shapedNote,
+    };
+  }
+  return {
+    command: command.split(placeholder).join(resolved.value),
+    shapedBy: resolved.shapedBy,
+    shapedNote: resolved.shapedNote,
+  };
+}
+
+/**
+ * Shape one command string: substitute the template variables the catalog
+ * authors into it and report which detection drove the result. A command
+ * without any `{{` marker is returned byte-identical and unshaped.
+ *
+ * @param {string} templateCommand Catalog command template.
+ * @param {CommandFacts} [facts] Facts gathered for the scanned project.
+ * @returns {{command: string, shapedBy: string|undefined, shapedNote: string|undefined}} The shaped command, the detection behind it, and the question to surface when shaping could not answer.
+ */
+export function shapeCommand(templateCommand, facts = {}) {
+  if (typeof templateCommand !== "string" || !templateCommand.includes("{{")) {
+    return {
+      command: templateCommand,
+      shapedBy: undefined,
+      shapedNote: undefined,
+    };
+  }
+  const windows = facts?.platform === "windows";
+  const platformFacts = factsForPlatform(facts, windows);
+  let command = templateCommand;
+  const shapedBy = new Set();
+  const notes = new Set();
+  for (const variable of SHAPE_VARIABLES) {
+    const result = substituteVariable(command, variable, platformFacts);
+    command = result.command;
+    if (result.shapedBy) {
+      shapedBy.add(result.shapedBy);
+    }
+    if (result.shapedNote) {
+      notes.add(result.shapedNote);
+    }
+  }
+  return {
+    command,
+    shapedBy: shapedBy.size ? [...shapedBy].sort().join("; ") : undefined,
+    shapedNote: notes.size ? [...notes].sort().join("; ") : undefined,
+  };
+}

package/lib/stages/postgen/parentEdge.js

@@ -0,0 +1,156 @@
+/**
+ * Root reachability repair for the `dependencies` graph.
+ *
+ * CycloneDX expects `metadata.component` to appear in `dependencies` with the
+ * first level of the tree in its `dependsOn`. That edge is emitted by each
+ * ecosystem leg from whatever manifest declares the direct dependencies, so a
+ * leg that resolves a project entirely from a lock file, an export command, or
+ * a pre-resolved graph can produce a complete transitive tree that no consumer
+ * can enter: every edge is present, but nothing is reachable from the root.
+ *
+ * This module repairs that shape at finalization time, independent of the
+ * ecosystem. When the parent has no outgoing edge and the tree does contain
+ * edges, the components that nothing else points to are the roots of the graph,
+ * and attaching them to the parent restores reachability for the whole tree.
+ *
+ * The repair is deliberately weaker than a leg that knows the manifest: a
+ * direct dependency that some transitive dependency also requires is not a
+ * root here and stays out of the parent's `dependsOn`. It is a safety net that
+ * keeps a tree traversable, not a replacement for emitting the edge at the
+ * source, and it records what it inferred so consumers can tell the two apart.
+ */
+
+import { readEnvironmentVariable } from "../../core/activity.js";
+import { thoughtLog } from "../../core/logger.js";
+
+/** Property recording how many root edges were inferred rather than observed. */
+export const INFERRED_ROOTS_PROPERTY = "cdx:bom:inferredRootDependencies";
+
+/**
+ * Collects the bom-refs of every component in the document, including nested
+ * subcomponents and the subcomponents of the parent itself.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ * @returns {Set<string>} Known component bom-refs
+ */
+function collectComponentRefs(bomJson) {
+  const refs = new Set();
+  const visit = (component) => {
+    if (!component) {
+      return;
+    }
+    if (component["bom-ref"]) {
+      refs.add(component["bom-ref"]);
+    }
+    for (const sub of component.components || []) {
+      visit(sub);
+    }
+  };
+  for (const component of bomJson?.components || []) {
+    visit(component);
+  }
+  for (const sub of bomJson?.metadata?.component?.components || []) {
+    visit(sub);
+  }
+  for (const service of bomJson?.services || []) {
+    if (service?.["bom-ref"]) {
+      refs.add(service["bom-ref"]);
+    }
+  }
+  return refs;
+}
+
+/**
+ * Adds the missing edge from the parent component to the roots of the
+ * dependency graph. A no-op unless the document has a parent component with no
+ * outgoing edge, a tree that already contains edges, and at least one component
+ * that nothing points to.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ *
+ * @returns {Object} The same BOM, repaired in place when applicable
+ */
+export function repairParentDependencyEdge(bomJson) {
+  if (readEnvironmentVariable("CDXGEN_PARENT_EDGE_REPAIR") === "false") {
+    return bomJson;
+  }
+  const dependencies = bomJson?.dependencies;
+  const parentRef = bomJson?.metadata?.component?.["bom-ref"];
+  if (!parentRef || !Array.isArray(dependencies) || !dependencies.length) {
+    return bomJson;
+  }
+  const lowerParentRef = parentRef.toLowerCase();
+  let parentEntry;
+  let hasEdges = false;
+  const referenced = new Set();
+  for (const adep of dependencies) {
+    if (!adep?.ref) {
+      continue;
+    }
+    if (adep.ref.toLowerCase() === lowerParentRef) {
+      parentEntry = adep;
+    }
+    if (adep.dependsOn?.length) {
+      hasEdges = true;
+    }
+    for (const ref of adep.dependsOn || []) {
+      referenced.add(ref);
+    }
+    // A crypto asset that is only ever provided is not a root of the tree.
+    for (const ref of adep.provides || []) {
+      referenced.add(ref);
+    }
+  }
+  if (parentEntry?.dependsOn?.length) {
+    return bomJson;
+  }
+  // Without a single edge there is no tree to enter, only a flat inventory such
+  // as a container image or an OS package list, where a fabricated root edge
+  // would assert a relationship that was never observed.
+  if (!hasEdges) {
+    return bomJson;
+  }
+  const componentRefs = collectComponentRefs(bomJson);
+  const roots = [];
+  for (const adep of dependencies) {
+    const ref = adep?.ref;
+    if (
+      !ref ||
+      ref.toLowerCase() === lowerParentRef ||
+      referenced.has(ref) ||
+      !componentRefs.has(ref)
+    ) {
+      continue;
+    }
+    roots.push(ref);
+  }
+  // Every component being a root means the observed edges all pointed at refs
+  // that no component in the document declares, so the graph cannot be trusted.
+  if (!roots.length || roots.length === componentRefs.size) {
+    return bomJson;
+  }
+  roots.sort();
+  if (parentEntry) {
+    parentEntry.dependsOn = roots;
+  } else {
+    dependencies.splice(0, 0, { ref: parentRef, dependsOn: roots });
+  }
+  if (!bomJson.metadata.properties) {
+    bomJson.metadata.properties = [];
+  }
+  const existing = bomJson.metadata.properties.find(
+    (p) => p.name === INFERRED_ROOTS_PROPERTY,
+  );
+  if (existing) {
+    existing.value = `${roots.length}`;
+  } else {
+    bomJson.metadata.properties.push({
+      name: INFERRED_ROOTS_PROPERTY,
+      value: `${roots.length}`,
+    });
+  }
+  thoughtLog(
+    `The parent component had no direct dependencies, so I attached the ${roots.length} component(s) that nothing else depends on to keep the tree reachable.`,
+  );
+  return bomJson;
+}

package/lib/stages/postgen/postgen.js

@@ -7,10 +7,12 @@ import { Purl } from "@cdxgen/cdx-purl";
 import {
   DEBUG_MODE,
   isDryRun,
+  isSecureMode,
   readEnvironmentVariable,
   resetActivityContext,
   setActivityContext,
 } from "../../core/activity.js";
+import { getRemediationCatalog } from "../../core/buildLedger.js";
 import { hasAnyProjectType } from "../../core/env.js";
 import {
   getTimestamp,
@@ -44,6 +46,23 @@ import { enhanceBom } from "../../inventory/licenseEnhancer.js";
 import { applyMcpPinningState } from "../../inventory/mcpPinning.js";
 import { buildReleaseNotesFromGit } from "../../inventory/source.js";
 import { extractTags, findBomType, textualMetadata } from "./annotator.js";
+import {
+  applyFormulationRunIdMarker,
+  applyIntrospectionToBom,
+  hasIntrospectionVerdict,
+} from "./introspection/annotate.js";
+import { collectCommandFacts } from "./introspection/commandFacts.js";
+import {
+  blockRemediationsForDryRun,
+  emitIntrospectionReports,
+  printIntrospectionSummary,
+} from "./introspection/emit.js";
+import {
+  isIntrospectionEnabled,
+  reflectOnRun,
+} from "./introspection/reflect.js";
+import { scoreReflection } from "./introspection/score.js";
+import { repairParentDependencyEdge } from "./parentEdge.js";
 import { sortBomCollections } from "./sortBom.js";
 import {
   applyComponentTypeFilter,
@@ -435,6 +454,94 @@ function buildAuditFindingsCitation(bomJson) {
   });
 }
 
+/**
+ * Run the build-introspection reflection over the final BOM, score it, write
+ * the reports, and carry the verdict inside the BOM as metadata properties and
+ * annotations. Introspection is opt-in; when disabled this is a no-op, and
+ * when enabled a reflection failure warns instead of failing the completed
+ * BOM.
+ *
+ * The CI gate is decided here but enforced by the CLI after the BOM is
+ * written, so a below-threshold score never costs the user their output.
+ *
+ * @param {Object} bomNSData BOM with namespaces object
+ * @param {Object} options CLI options
+ * @param {string} [filePath] Source path that was scanned
+ *
+ * @returns {Promise<Object>} The same bomNSData, with `reflection` (carrying its `scoring`) attached when introspection ran
+ */
+async function applyIntrospection(bomNSData, options, filePath) {
+  if (!isIntrospectionEnabled(options) || !bomNSData?.bomJson) {
+    return bomNSData;
+  }
+  // Evidence collection re-processes a finished BOM through a fresh wrapper,
+  // but that pass carries neither the scanned path nor the generation's
+  // ecosystem context: its ledger events belong to the evinse probes and its
+  // marker scan finds nothing, so it would grade a project it never saw. The
+  // verdict describes how the BOM was generated, so it stays with the pass
+  // that generated it — the document itself is what carries that across.
+  if (bomNSData.reflection || hasIntrospectionVerdict(bomNSData.bomJson)) {
+    return bomNSData;
+  }
+  try {
+    const reflection = await reflectOnRun(bomNSData.bomJson, options, {
+      projectPath: filePath || options.filePath || "",
+    });
+    reflection.scoring = scoreReflection(reflection, getRemediationCatalog(), {
+      secureMode: isSecureMode,
+      inContainer: readEnvironmentVariable("CDXGEN_IN_CONTAINER") === "true",
+      commandFacts: collectCommandFacts(filePath || options.filePath || ""),
+    });
+    // Report consumers correlate a report with the BOM it describes through
+    // these two facts, so they travel on the reflection document itself.
+    reflection.bom = {
+      serialNumber: bomNSData.bomJson?.serialNumber,
+      componentCount: Array.isArray(bomNSData.bomJson?.components)
+        ? bomNSData.bomJson.components.length
+        : 0,
+    };
+    bomNSData.reflection = reflection;
+    if (isDryRun) {
+      blockRemediationsForDryRun(reflection.scoring);
+    }
+    // A document at a spec version that predates annotations still carries
+    // the metadata properties; only the annotations are version-gated.
+    const annotationsSupported =
+      normalizeCycloneDxSpecVersion(
+        options?.specVersion || bomNSData.bomJson?.specVersion,
+      ) >= 1.5;
+    applyFormulationRunIdMarker(bomNSData.bomJson, reflection.runId);
+    applyIntrospectionToBom(bomNSData.bomJson, reflection, reflection.scoring, {
+      annotations: annotationsSupported,
+    });
+    const delivery = emitIntrospectionReports(
+      reflection,
+      reflection.scoring,
+      options,
+    );
+    printIntrospectionSummary(reflection.scoring, delivery);
+    const threshold = options?.introspectFailBelow;
+    if (typeof threshold === "number" && Number.isFinite(threshold)) {
+      const score = reflection.scoring.overallScore;
+      bomNSData.introspectionGate = {
+        threshold,
+        score,
+        passed: score >= threshold,
+      };
+    }
+    if (!reflection.ledgerComplete) {
+      console.warn(
+        "Build introspection: the ledger is incomplete (buffer truncated or recorder event); treat the verdict with care and re-run with CDXGEN_INTROSPECT_LEDGER set.",
+      );
+    }
+  } catch (err) {
+    console.warn(
+      `Build introspection failed to complete and was skipped: ${err?.message}`,
+    );
+  }
+  return bomNSData;
+}
+
 /**
  * Filter and enhance BOM post generation.
  *
@@ -442,9 +549,9 @@ function buildAuditFindingsCitation(bomJson) {
  * @param {Object} options CLI options
  * @param {string} [filePath] Source path used for formulation and metadata context
  *
- * @returns {Object} Modified bomNSData
+ * @returns {Promise<Object>} Modified bomNSData
  */
-export function postProcess(bomNSData, options, filePath) {
+export async function postProcess(bomNSData, options, filePath) {
   let jsonPayload = bomNSData.bomJson;
   if (
     typeof bomNSData.bomJson === "string" ||
@@ -466,6 +573,9 @@ export function postProcess(bomNSData, options, filePath) {
   );
   bomNSData.bomJson = applyReleaseNotes(bomNSData.bomJson, options, filePath);
   bomNSData.bomJson = applyComponentTypeFilter(bomNSData.bomJson, options);
+  // Filtering can leave the tree without a way in, so this runs on the final
+  // component set and before annotations, which report on reachability.
+  bomNSData.bomJson = repairParentDependencyEdge(bomNSData.bomJson);
   bomNSData.bomJson = applySpecVersionCompatibility(bomNSData.bomJson, options);
   bomNSData.bomJson = validateTlpClassification(bomNSData.bomJson, options);
   // Support for automatic annotations
@@ -495,6 +605,9 @@ export function postProcess(bomNSData, options, filePath) {
   cleanupEnv(options);
   cleanupTmpDir();
   sortBomCollections(bomNSData.bomJson);
+  // Reflection reads the finished BOM, so it runs after sorting; it returns
+  // its verdict alongside the BOM instead of mutating it.
+  await applyIntrospection(bomNSData, options, filePath);
   return bomNSData;
 }
 

package/lib/stages/postgen/ruleEngine.js

@@ -494,6 +494,23 @@ function registerCdxHelpers(expression, helpers = {}) {
   expression.registerFunction("formulationComponents", (bomJson) =>
     getFormulationComponents(bomJson),
   );
+  // Formulation-derived rules need to know whether the formulation section
+  // describes the run being reflected (whose probes the ledger already
+  // counted) or a foreign BOM's record. The caller that read the evidence
+  // passes its origin verdict through the options; without one, rules gated
+  // on a specific origin stay silent.
+  expression.registerFunction(
+    "formulationOrigin",
+    () => helpers?.formulationEvidence?.origin || "unknown",
+  );
+  // The toolchain mismatch a foreign BOM's formulation proves: the recorded
+  // version of this runtime's own family differs from the runtime in use, so
+  // the record describes another machine. Computed by the caller, which owns
+  // the runtime facts.
+  expression.registerFunction(
+    "formulationRuntimeMismatch",
+    () => helpers?.formulationEvidence?.runtimeMismatch,
+  );
   return expression;
 }