@clear-capabilities/agentic-security-scanner 0.172.1 → 0.173.0

package/dist/3653.index.js

@@ -0,0 +1,450 @@
+export const id = 3653;
+export const ids = [3653];
+export const modules = {
+
+/***/ 63653:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   computeGraphDiff: () => (/* binding */ computeGraphDiff)
+/* harmony export */ });
+/* unused harmony exports WATCHED_FLOW_FIELDS, validateGraphDiff */
+/* harmony import */ var _graph_snapshot_js__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(14870);
+/* harmony import */ var _ids_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(19051);
+/* harmony import */ var _dataflow_privacy_governance_js__WEBPACK_IMPORTED_MODULE_2__ = __webpack_require__(24701);
+// graph-diff.js — M4 deliverable #9 (FR-503 §14, DFG-022), sub-project
+// 8b, Task 1: the GraphDiff extension contract + computeGraphDiff + honest
+// change-cause classification.
+//
+// Mirrors graph-snapshot.js's/obligation-mapping.js's/decision-story.js's
+// own shape exactly: a record is explicitly NOT a DataFlowGraph v1 entity
+// (§10.10 — "associated with, but not required inside, the immutable base
+// graph"), never added to dataflow-graph.schema.json, never routed
+// through validate.js's validateGraph(). See ids.js's diffId() for the id
+// scheme.
+//
+// This module ONLY computes a diff between two already-persisted
+// GraphSnapshot records and classifies why each removed flow disappeared,
+// as far as real, checkable signals allow. It does NOT decide what a
+// caller should DO with a GraphDiff (no CLI, no drift-policy matching —
+// see this sub-project's own task brief: those are Tasks 2/3).
+//
+// ── Design judgment calls made in this file (disclosed, not hidden) ──
+//
+// 1. WATCHED_FLOW_FIELDS includes `governanceRefs`, not just the four
+//    scalar fields the task brief names literally
+//    (protectionSummary/policyVerdict/handling/coverageStatus). Read
+//    directly against dataflow-graph.schema.json's own flow $def (§145 of
+//    that file) and graph-builder.js's real flow-construction loop:
+//    `flow.governanceRefs` is a real, populated field (coverage.js's
+//    `resolveGovernanceRefs` default, keyed by
+//    dataflow/privacy-governance.js's own GOVERNANCE_FIELDS —
+//    purpose/lawfulBasis/subject/retention/residency/recipient/transfer/
+//    minimization/consent/access/deletion), never a fabricated shape. A
+//    "retention/deletion or lawful-basis change" — AC-27's own bullet
+//    list — can ONLY show up as a governanceRefs difference, since none
+//    of the other four watched fields carry that information at all. The
+//    diff compares it value-by-value over GOVERNANCE_FIELDS (never a
+//    bare object-identity/JSON-string check), emitting one changed-field
+//    entry per differing governance field (`governanceRefs.<field>`), so
+//    a caller learns WHICH governance fact changed, not just "something
+//    in governance changed."
+//
+// 2. Non-flow removed entities (nodes/edges/dataElements) always get
+//    causeClassification: 'application_change'. The task brief's Global
+//    Constraint says the coverage-regression check applies "per removed
+//    flow entry ONLY" — read literally, that leaves open what a removed
+//    node/edge/dataElement gets. The same reasoning the brief gives for
+//    added/changed entries applies here too ("no other real signal
+//    exists... do not invent one") — a removed node/edge/dataElement has
+//    no flow-level protection/policy verdict to have regressed, and this
+//    module has no coverage-completeness signal scoped to a bare node or
+//    edge (coverage.js's own ledger is source/sink/language-level, not
+//    node/edge-level) — so 'application_change' is the only honest
+//    default for those three entity kinds.
+//
+// 3. Change-cause classification for flows.changed entries is always
+//    'application_change', per the brief's own literal instruction — a
+//    CHANGED flow (same id, different watched field) can never be a
+//    coverage regression by definition: coverage regression means the
+//    engine stopped seeing something, and a flow whose id is still
+//    present in both snapshots was, by construction, seen in both.
+//
+// 4. Reidentification (fix round 1, Important 1). flowId's own
+//    discriminator (graph-builder.js's `ids.flowId(src.id, snk.id,
+//    [de.id], [p.shape, g.grade, sortedT.join(',')])` call site) includes
+//    `evidenceGrade`/`transformationIds` — neither is an application-level
+//    fact; `evidenceGrade` in particular is the analyzer's own confidence
+//    in the flow. When either changes between two scans of literally the
+//    same real-world (source, sink, dataElementIds) flow — the commonest
+//    cause is a refactor the analyzer resolves less/more precisely — the
+//    flow mints a NEW flowId, and a naive id-set diff would report it as
+//    an unrelated remove+add pair: a fabricated `firstSeen` on the added
+//    entry, and a `removed` entry reading as "this flow went away" when it
+//    did not. `_flowCorrelationKey` (below) correlates a removed/added
+//    pair by REAL application identity — (source, sink, sorted
+//    dataElementIds) — instead, and computeGraphDiff marks a correlated
+//    pair `causeClassification: 'reidentified'` with a pointer
+//    (`reidentifiedFrom`/`reidentifiedTo`) at its counterpart, rather than
+//    silently treating them as independent. This never substitutes for
+//    flowId identity anywhere else in this file — it exists ONLY to
+//    detect this one reidentification case.
+//
+//    A direct, disclosed consequence: `WATCHED_FLOW_FIELDS`'s `handling`
+//    entry is near-unreachable in the `changed.flows` bucket for the same
+//    root cause — a `handling` change almost always also changes
+//    `transformationIds`, which is itself part of flowId's own
+//    discriminator, so it manifests as a reidentification (remove+add,
+//    correlated) rather than surviving as a same-id `changed.flows` entry.
+//    This is a real, disclosed limitation of the current flowId shape, not
+//    a bug in this file.
+
+
+
+
+
+const DIFF_VERSION = '1.0.0';
+
+const ENTITY_ARRAYS = Object.freeze(['nodes', 'edges', 'dataElements', 'flows']);
+
+// See judgment call #1 above for why `governanceRefs` is included
+// alongside the brief's own literal four.
+const WATCHED_FLOW_FIELDS = Object.freeze([
+  'protectionSummary', 'policyVerdict', 'handling', 'coverageStatus', 'governanceRefs',
+]);
+
+function _isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
+function _isPlainObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+function _idMap(arr) {
+  const m = new Map();
+  for (const e of arr ?? []) {
+    if (e && typeof e.id === 'string') m.set(e.id, e);
+  }
+  return m;
+}
+
+/** Sorted id-set diff between two id->entity Maps. Deterministic order. */
+function _idSetDiff(beforeMap, afterMap) {
+  const added = [];
+  const removed = [];
+  for (const id of afterMap.keys()) if (!beforeMap.has(id)) added.push(id);
+  for (const id of beforeMap.keys()) if (!afterMap.has(id)) removed.push(id);
+  added.sort();
+  removed.sort();
+  return { added, removed };
+}
+
+// Correlates a flow across a commit boundary by APPLICATION identity
+// (source, sink, dataElementIds) — deliberately NOT by flowId, since
+// flowId's own discriminator includes evidenceGrade/transformationIds
+// (engine-confidence/shape signals, not application facts — see
+// graph-builder.js's ids.flowId call site), so the SAME real-world flow
+// can legitimately mint two different ids across two scans. Never a
+// substitute for flowId identity elsewhere in this file — used ONLY to
+// detect this one specific reidentification case.
+function _flowCorrelationKey(flow) {
+  const des = Array.isArray(flow.dataElementIds) ? [...flow.dataElementIds].sort() : [];
+  return `${flow.source}|${flow.sink}|${des.join(',')}`;
+}
+
+function _addedEntry(id, afterSnapshot) {
+  return {
+    id,
+    causeClassification: 'application_change',
+    firstSeen: { commit: afterSnapshot.commit, capturedAt: afterSnapshot.capturedAt },
+  };
+}
+
+function _removedEntry(id, beforeSnapshot, causeClassification, extra = {}) {
+  return {
+    id,
+    causeClassification,
+    lastSeen: { commit: beforeSnapshot.commit, capturedAt: beforeSnapshot.capturedAt },
+    ...extra,
+  };
+}
+
+/**
+ * Diffs one flow's WATCHED_FLOW_FIELDS between two snapshots of the SAME
+ * flow id. Returns an array of {field, before, after} — empty when
+ * nothing watched differs. Never a bare "something changed" — every
+ * entry names the exact field and its real before/after value.
+ */
+function _diffFlowFields(before, after) {
+  const changes = [];
+  for (const field of WATCHED_FLOW_FIELDS) {
+    if (field === 'governanceRefs') {
+      const b = before.governanceRefs ?? {};
+      const a = after.governanceRefs ?? {};
+      for (const gField of _dataflow_privacy_governance_js__WEBPACK_IMPORTED_MODULE_2__/* .GOVERNANCE_FIELDS */ .n4) {
+        const bv = b[gField] ?? null;
+        const av = a[gField] ?? null;
+        if (JSON.stringify(bv) !== JSON.stringify(av)) {
+          changes.push({ field: `governanceRefs.${gField}`, before: bv, after: av });
+        }
+      }
+      continue;
+    }
+    const bv = before[field] ?? null;
+    const av = after[field] ?? null;
+    if (bv !== av) changes.push({ field, before: bv, after: av });
+  }
+  return changes;
+}
+
+/**
+ * Real, checkable coverage-completeness signals — read directly against
+ * coverage.js's own buildCoverageLedger output shape: `sources.matched`,
+ * `sinks.callStatementSites`, `languages[].filesAnalyzed`. Returns an
+ * array of reason strings naming exactly which completeness field
+ * regressed (empty when none did — never a guess in the regression
+ * direction).
+ */
+function _coverageRegressionReasons(coverageBefore, coverageAfter) {
+  const b = coverageBefore ?? {};
+  const a = coverageAfter ?? {};
+  const reasons = [];
+
+  const beforeMatched = b.sources?.matched ?? 0;
+  const afterMatched = a.sources?.matched ?? 0;
+  if (afterMatched < beforeMatched) {
+    reasons.push(`sources.matched decreased (${beforeMatched} -> ${afterMatched})`);
+  }
+
+  const beforeSites = b.sinks?.callStatementSites ?? 0;
+  const afterSites = a.sinks?.callStatementSites ?? 0;
+  if (afterSites < beforeSites) {
+    reasons.push(`sinks.callStatementSites decreased (${beforeSites} -> ${afterSites})`);
+  }
+
+  const beforeLangs = new Map((b.languages ?? []).map((l) => [l.language, l.filesAnalyzed]));
+  for (const l of a.languages ?? []) {
+    const prevAnalyzed = beforeLangs.get(l.language);
+    if (prevAnalyzed != null && l.filesAnalyzed < prevAnalyzed) {
+      reasons.push(`languages.${l.language}.filesAnalyzed decreased (${prevAnalyzed} -> ${l.filesAnalyzed})`);
+    }
+  }
+
+  return reasons;
+}
+
+/**
+ * Structural validation only — mirrors graph-snapshot.js's own
+ * validateGraphSnapshot {valid, errors} shape and "never throws"
+ * contract. Checks the record's own top-level shape plus each
+ * added/removed/changed entry's own minimal shape; never cross-references
+ * a real graph (this module's validator, like every §10.10 extension
+ * contract's own validator, is a pure shape check).
+ */
+function validateGraphDiff(record) {
+  const errors = [];
+  const err = (p, message) => errors.push({ path: p, message });
+
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    err('$', 'GraphDiff record must be an object');
+    return { valid: false, errors };
+  }
+
+  if (!_isNonEmptyString(record.id) || !record.id.startsWith('diff:')) {
+    err('$.id', 'id is required and must start with "diff:"');
+  }
+  if (!_isNonEmptyString(record.version)) err('$.version', 'version is required');
+  if (!_isNonEmptyString(record.beforeSnapshotId)) err('$.beforeSnapshotId', 'beforeSnapshotId is required');
+  if (!_isNonEmptyString(record.afterSnapshotId)) err('$.afterSnapshotId', 'afterSnapshotId is required');
+  if (!_isNonEmptyString(record.generatedAt)) err('$.generatedAt', 'generatedAt is required');
+
+  if (!_isPlainObject(record.comparability)) {
+    err('$.comparability', 'comparability is required and must be an object');
+  } else {
+    if (typeof record.comparability.comparable !== 'boolean') {
+      err('$.comparability.comparable', 'comparability.comparable must be a boolean');
+    }
+    if (!Array.isArray(record.comparability.reasons)) {
+      err('$.comparability.reasons', 'comparability.reasons must be an array');
+    }
+  }
+
+  const _checkEntryArray = (bucketPath, arr, requireFirstSeen, requireLastSeen) => {
+    if (!Array.isArray(arr)) {
+      err(bucketPath, `${bucketPath} must be an array`);
+      return;
+    }
+    arr.forEach((entry, i) => {
+      const p = `${bucketPath}[${i}]`;
+      if (!_isPlainObject(entry)) { err(p, `${p} must be an object`); return; }
+      if (!_isNonEmptyString(entry.id)) err(`${p}.id`, `${p}.id is required`);
+      if (!_isNonEmptyString(entry.causeClassification)) err(`${p}.causeClassification`, `${p}.causeClassification is required`);
+      if (requireFirstSeen && !_isPlainObject(entry.firstSeen)) err(`${p}.firstSeen`, `${p}.firstSeen is required and must be an object`);
+      if (requireLastSeen && !_isPlainObject(entry.lastSeen)) err(`${p}.lastSeen`, `${p}.lastSeen is required and must be an object`);
+    });
+  };
+
+  if (!_isPlainObject(record.added)) {
+    err('$.added', 'added is required and must be an object');
+  } else {
+    for (const key of ENTITY_ARRAYS) _checkEntryArray(`$.added.${key}`, record.added[key], true, false);
+  }
+
+  if (!_isPlainObject(record.removed)) {
+    err('$.removed', 'removed is required and must be an object');
+  } else {
+    for (const key of ENTITY_ARRAYS) _checkEntryArray(`$.removed.${key}`, record.removed[key], false, true);
+  }
+
+  if (!_isPlainObject(record.changed)) {
+    err('$.changed', 'changed is required and must be an object');
+  } else if (!Array.isArray(record.changed.flows)) {
+    err('$.changed.flows', 'changed.flows must be an array');
+  } else {
+    record.changed.flows.forEach((entry, i) => {
+      const p = `$.changed.flows[${i}]`;
+      if (!_isPlainObject(entry)) { err(p, `${p} must be an object`); return; }
+      if (!_isNonEmptyString(entry.id)) err(`${p}.id`, `${p}.id is required`);
+      if (!_isNonEmptyString(entry.causeClassification)) err(`${p}.causeClassification`, `${p}.causeClassification is required`);
+      if (!Array.isArray(entry.changes) || entry.changes.length === 0) {
+        err(`${p}.changes`, `${p}.changes must be a non-empty array naming which field(s) changed`);
+      }
+    });
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+/**
+ * Diffs two GraphSnapshot records. Refuses (throws, naming the real
+ * reasons) on an incomparable pair — never silently diffs across one.
+ *
+ * added/removed: an ID-set diff across nodes/edges/dataElements/flows.
+ * changed: flows ONLY — every flow id present in both snapshots whose
+ * WATCHED_FLOW_FIELDS differ.
+ *
+ * Change-cause classification: every added/changed entry gets
+ * 'application_change' (no other real signal exists for those — see this
+ * file's own header). Every removed FLOW entry gets
+ * 'possible_coverage_regression' when the AFTER snapshot's real coverage
+ * is measurably lower on a real completeness field, otherwise
+ * 'application_change'; every removed node/edge/dataElement entry gets
+ * 'application_change' unconditionally (see judgment call #2 above).
+ */
+function computeGraphDiff(snapshotBefore, snapshotAfter, opts = {}) {
+  const { comparable, reasons } = (0,_graph_snapshot_js__WEBPACK_IMPORTED_MODULE_0__/* .snapshotsComparable */ .mx)(snapshotBefore, snapshotAfter);
+  if (!comparable) {
+    throw new Error(`computeGraphDiff: snapshots are not comparable — ${reasons.join('; ')}`);
+  }
+
+  const graphBefore = snapshotBefore.graph ?? {};
+  const graphAfter = snapshotAfter.graph ?? {};
+
+  const coverageRegressionReasons = _coverageRegressionReasons(snapshotBefore.coverage, snapshotAfter.coverage);
+  const flowRemovalCause = coverageRegressionReasons.length ? 'possible_coverage_regression' : 'application_change';
+
+  const added = {};
+  const removed = {};
+  const flowMaps = {};
+
+  for (const key of ENTITY_ARRAYS) {
+    const beforeMap = _idMap(graphBefore[key]);
+    const afterMap = _idMap(graphAfter[key]);
+    if (key === 'flows') {
+      flowMaps.before = beforeMap;
+      flowMaps.after = afterMap;
+    }
+
+    const { added: addedIds, removed: removedIds } = _idSetDiff(beforeMap, afterMap);
+
+    // Reidentification pairing (see judgment call #4 in this file's own
+    // header for the full reasoning): group removed/added flow ids by
+    // _flowCorrelationKey, pair them 1:1 (sorted by id, index-aligned)
+    // within each matching key. A pair is a re-identification, not a real
+    // remove+add. Any surplus on either side (uncommon — would need >1
+    // flow sharing the same correlation key on one side) falls through to
+    // the existing add/remove logic unchanged.
+    const reidentifiedFrom = new Map(); // addedId -> removedId
+    const reidentifiedTo = new Map();   // removedId -> addedId
+    if (key === 'flows') {
+      const removedByKey = new Map();
+      for (const id of removedIds) {
+        const f = beforeMap.get(id);
+        const k = _flowCorrelationKey(f);
+        if (!removedByKey.has(k)) removedByKey.set(k, []);
+        removedByKey.get(k).push(id);
+      }
+      const addedByKey = new Map();
+      for (const id of addedIds) {
+        const f = afterMap.get(id);
+        const k = _flowCorrelationKey(f);
+        if (!addedByKey.has(k)) addedByKey.set(k, []);
+        addedByKey.get(k).push(id);
+      }
+      for (const [k, removedGroup] of removedByKey) {
+        const addedGroup = addedByKey.get(k);
+        if (!addedGroup) continue;
+        removedGroup.sort();
+        addedGroup.sort();
+        const n = Math.min(removedGroup.length, addedGroup.length);
+        for (let i = 0; i < n; i++) {
+          reidentifiedTo.set(removedGroup[i], addedGroup[i]);
+          reidentifiedFrom.set(addedGroup[i], removedGroup[i]);
+        }
+      }
+    }
+
+    added[key] = addedIds.map((id) => {
+      const entry = _addedEntry(id, snapshotAfter);
+      if (key === 'flows' && reidentifiedFrom.has(id)) {
+        entry.causeClassification = 'reidentified';
+        entry.reidentifiedFrom = reidentifiedFrom.get(id);
+      }
+      return entry;
+    });
+
+    if (key === 'flows') {
+      removed[key] = removedIds.map((id) => {
+        const extra = coverageRegressionReasons.length ? { coverageRegressionReasons } : {};
+        const entry = _removedEntry(id, snapshotBefore, flowRemovalCause, extra);
+        if (reidentifiedTo.has(id)) {
+          entry.causeClassification = 'reidentified';
+          entry.reidentifiedTo = reidentifiedTo.get(id);
+        }
+        return entry;
+      });
+    } else {
+      removed[key] = removedIds.map((id) => _removedEntry(id, snapshotBefore, 'application_change'));
+    }
+  }
+
+  const changedFlows = [];
+  for (const [id, beforeFlow] of flowMaps.before) {
+    const afterFlow = flowMaps.after.get(id);
+    if (!afterFlow) continue; // removed — already handled above
+    const changes = _diffFlowFields(beforeFlow, afterFlow);
+    if (changes.length > 0) {
+      changedFlows.push({ id, causeClassification: 'application_change', changes });
+    }
+  }
+  changedFlows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  const record = {
+    id: (0,_ids_js__WEBPACK_IMPORTED_MODULE_1__/* .diffId */ .Jd)({ beforeSnapshotId: snapshotBefore.id, afterSnapshotId: snapshotAfter.id }),
+    version: DIFF_VERSION,
+    beforeSnapshotId: snapshotBefore.id,
+    afterSnapshotId: snapshotAfter.id,
+    comparability: { comparable: true, reasons: [] },
+    added,
+    removed,
+    changed: { flows: changedFlows },
+    generatedAt: opts.generatedAt ?? new Date().toISOString(),
+  };
+
+  const { valid, errors } = validateGraphDiff(record);
+  if (!valid) {
+    throw new Error(`computeGraphDiff: internal error — produced an invalid GraphDiff: ${JSON.stringify(errors)}`);
+  }
+  return record;
+}
+
+
+/***/ })
+
+};

package/dist/3822.index.js

@@ -0,0 +1,131 @@
+export const id = 3822;
+export const ids = [3822];
+export const modules = {
+
+/***/ 3822:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+/* harmony export */ __webpack_require__.d(__webpack_exports__, {
+/* harmony export */   buildArtifactProvenanceGraph: () => (/* binding */ buildArtifactProvenanceGraph),
+/* harmony export */   traceArtifactProvenanceGraph: () => (/* binding */ traceArtifactProvenanceGraph)
+/* harmony export */ });
+// PRD 5 P0 §6 — Provenance Graph: Git Commit -> Build -> OCI Digest -> SBOM
+// Component -> Finding -> Deployment.
+//
+// Naming: the exported field is `artifactProvenanceGraph` and the builder is
+// `buildArtifactProvenanceGraph` — never a bare `.provenance`/`*Provenance`,
+// per this repo's own naming discipline (5 unrelated existing uses of
+// "provenance"; see docs/implementation-status/source-to-artifact-provenance.md).
+//
+// This function does no new detection — every node/edge is assembled from
+// evidence `inventory.js`/`vuln-correlate.js` already computed. The one
+// exception is the Git-Commit edge, whose only evidence source is the
+// standard `org.opencontainers.image.revision` build label; when absent the
+// commit node is explicitly `known: false`, never inferred from git history
+// (an image's build label is the only trustworthy claim of "which commit
+// built this" — matching it against local git history by heuristic would be
+// a confident-looking guess, the exact failure mode PRD 5's signature-state
+// discipline exists to prevent elsewhere in this same PRD).
+const REVISION_LABEL = 'org.opencontainers.image.revision';
+
+function componentId(c) {
+  return c.purl || `${c.ecosystem}:${c.name}@${c.version}`;
+}
+
+/**
+ * `inventory` is `inventory.js#buildImageInventory`'s `inventory`.
+ * `vulnerabilities` is `vuln-correlate.js`'s `queryOSVFn` result (only
+ * `type: 'vulnerable_dep'` entries become Finding nodes — the no_lockfile",
+ * "unpinned_dep" structural checks don't bind to a specific component and
+ * are not part of this graph). `deployment`, if supplied, is an
+ * OPERATOR-DECLARED record (`{ id, environment, evidence }`) — this codebase
+ * has no mechanism anywhere that discovers "which digest is running where"
+ * on its own (`lineage/deployment/` models topology, not running digests),
+ * so a missing `deployment` argument means the graph simply stops at the
+ * OCI Digest / SBOM Component / Finding nodes, never a fabricated edge.
+ */
+function buildArtifactProvenanceGraph({ inventory, vulnerabilities = [], deployment = null }) {
+  if (!inventory || typeof inventory.digest !== 'string') {
+    throw new TypeError('buildArtifactProvenanceGraph requires an inventory with a digest');
+  }
+  const nodes = [];
+  const edges = [];
+
+  const commitSha = inventory.buildLabels ? inventory.buildLabels[REVISION_LABEL] || null : null;
+  const commitId = `commit:${commitSha || 'unknown'}`;
+  const buildId = `build:${inventory.digest}`;
+  const digestId = `digest:${inventory.digest}`;
+
+  nodes.push({ id: commitId, kind: 'gitCommit', sha: commitSha, known: !!commitSha });
+  nodes.push({ id: buildId, kind: 'build', digest: inventory.digest, labels: inventory.buildLabels || {} });
+  nodes.push({ id: digestId, kind: 'ociDigest', digest: inventory.digest, digestKind: inventory.digestKind, repoTags: inventory.repoTags || [] });
+
+  edges.push({
+    from: commitId, to: buildId,
+    evidence: commitSha ? `label:${REVISION_LABEL}` : 'none',
+  });
+  edges.push({ from: buildId, to: digestId, evidence: 'same-archive' });
+
+  const components = [...(inventory.osPackages || []), ...(inventory.appPackages || [])];
+  for (const c of components) {
+    const compId = `component:${componentId(c)}`;
+    nodes.push({ id: compId, kind: 'sbomComponent', purl: c.purl || null, name: c.name, version: c.version, ecosystem: c.ecosystem });
+    edges.push({ from: digestId, to: compId, evidence: 'inventory' });
+  }
+
+  const vulnDeps = (vulnerabilities || []).filter((v) => v.type === 'vulnerable_dep');
+  for (const v of vulnDeps) {
+    const compId = `component:${v.purl || `${v.ecosystem}:${v.name}@${v.version}`}`;
+    const findingId = `finding:${v.osvId}:${v.purl || `${v.ecosystem}:${v.name}@${v.version}`}`;
+    nodes.push({ id: findingId, kind: 'finding', osvId: v.osvId, cveAliases: v.cveAliases || [], severity: v.severity });
+    edges.push({ from: compId, to: findingId, evidence: 'osv' });
+  }
+
+  if (deployment) {
+    if (typeof deployment.id !== 'string') throw new TypeError('a supplied deployment record requires an "id"');
+    const deploymentId = `deployment:${deployment.id}`;
+    nodes.push({ id: deploymentId, kind: 'deployment', environment: deployment.environment || null, declaredDigest: deployment.digest || null });
+    edges.push({
+      from: digestId, to: deploymentId,
+      evidence: deployment.evidence || 'operator-declared',
+      digestMatches: deployment.digest ? deployment.digest === inventory.digest : null,
+    });
+  }
+
+  return { nodes, edges };
+}
+
+/**
+ * Walks the graph from a commit or digest to every reachable Finding/Deployment
+ * node — the `provenance trace` CLI command's query surface.
+ */
+function traceArtifactProvenanceGraph(graph, fromId) {
+  if (!graph || !Array.isArray(graph.nodes) || !Array.isArray(graph.edges)) {
+    throw new TypeError('traceArtifactProvenanceGraph requires a graph with nodes/edges arrays');
+  }
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  if (!byId.has(fromId)) return { found: false, path: [] };
+  const adjacency = new Map();
+  for (const e of graph.edges) {
+    if (!adjacency.has(e.from)) adjacency.set(e.from, []);
+    adjacency.get(e.from).push(e);
+  }
+  const visited = new Set([fromId]);
+  const queue = [fromId];
+  const reached = [];
+  while (queue.length) {
+    const cur = queue.shift();
+    for (const e of adjacency.get(cur) || []) {
+      if (visited.has(e.to)) continue;
+      visited.add(e.to);
+      reached.push({ node: byId.get(e.to), via: e });
+      queue.push(e.to);
+    }
+  }
+  return { found: true, root: byId.get(fromId), reached };
+}
+
+
+/***/ })
+
+};