@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/graph/adapters/semantic.js

@@ -0,0 +1,89 @@
+//
+// adapters/semantic.js: read-only view over a SemanticGraph v1
+// (ir/semantic-graph.js). Imports only the schema constants and validator; it
+// never builds or mutates a graph.
+//
+// A graph that fails `validateGraph`, or whose major version is not the
+// supported one, is REJECTED (INCOMPATIBLE_VERSION / INVALID_GRAPH) rather than
+// partially adapted.
+//
+// Entities: symbol, callSite, allocation, fieldAccess, valueOrigin,
+// serviceBoundary, storageEdge, sanitizer, guard (singular names of the
+// graph's own lists). The semantic graph stores references as id fields, not
+// an edge list, so the relation edges here are DERIVED (origin 'derived') and
+// get deterministic ids; the underlying confidence tier becomes the evidence
+// grade, and an unresolved call is carried as an `unknowns` entry, never as a
+// fabricated callee edge.
+//
+//   symbol --declaration--> callSite      (the caller declares/contains it)
+//   symbol --declaration--> valueOrigin / fieldAccess / allocation
+//   callSite --calls--> symbol            (resolved calls only)
+//   valueOrigin --data_flow--> callSite   (an argument origin feeds the call)
+
+import {
+  SEMANTIC_GRAPH_SCHEMA, SUPPORTED_MAJOR, validateGraph, ENTITY_LISTS,
+} from '../../ir/semantic-graph.js';
+import { GraphViewError, digestOf } from '../refs.js';
+import { IndexedGraphView, local } from '../view.js';
+
+export const SEMANTIC_ADAPTER_VERSION = '1.0.0';
+
+const SINGULAR = {
+  symbols: 'symbol', callSites: 'callSite', allocations: 'allocation', fieldAccesses: 'fieldAccess',
+  valueOrigins: 'valueOrigin', serviceBoundaries: 'serviceBoundary', storageEdges: 'storageEdge',
+  sanitizers: 'sanitizer', guards: 'guard',
+};
+
+/**
+ * @param {object} graph  SemanticGraph v1 (buildSemanticGraph output)
+ * @param {{repository:string}} opts
+ */
+export function semanticView(graph, opts) {
+  const m = typeof graph?.schemaVersion === 'string' ? /^(\d+)\./.exec(graph.schemaVersion) : null;
+  if (graph?.schema === SEMANTIC_GRAPH_SCHEMA && m && Number(m[1]) !== SUPPORTED_MAJOR) {
+    throw new GraphViewError('INCOMPATIBLE_VERSION', `semantic graph major ${m[1]} is not supported (supported: ${SUPPORTED_MAJOR})`, { schemaVersion: graph.schemaVersion });
+  }
+  const v = validateGraph(graph);
+  if (!v.ok) throw new GraphViewError('INVALID_GRAPH', `semantic graph failed validation: ${v.errors[0].code} at ${v.errors[0].path}`, { errors: v.errors.slice(0, 5) });
+
+  const graphDigest = digestOf(graph);
+  const nodes = [];
+  for (const list of ENTITY_LISTS) {
+    for (const e of graph[list]) {
+      nodes.push({ entityKind: SINGULAR[list], localId: e.id, native: e, summary: { file: e.file, line: e.line, tier: e.confidence?.tier ?? null } });
+    }
+  }
+  const edges = [];
+  const edge = (relation, from, to, grade, extra = {}) => {
+    edges.push({
+      id: `sgedge:${relation}:${from.localId}:${to.localId}`, relation, origin: 'derived',
+      from, to, evidence: { grade, source: 'semantic-graph' }, unknowns: extra.unknowns ?? [], attrs: extra.attrs ?? {}, native: null,
+    });
+  };
+  for (const c of graph.callSites) {
+    edge('declaration', local('symbol', c.caller), local('callSite', c.id), c.confidence.tier);
+    if (c.callee) edge('calls', local('callSite', c.id), local('symbol', c.callee), c.confidence.tier, { attrs: { resolution: c.resolution } });
+    for (const a of c.args || []) {
+      if (a.origin) edge('data_flow', local('valueOrigin', a.origin), local('callSite', c.id), c.confidence.tier, { attrs: { argIndex: a.index } });
+    }
+  }
+  for (const o of graph.valueOrigins) if (o.symbol) edge('declaration', local('symbol', o.symbol), local('valueOrigin', o.id), o.confidence.tier);
+  for (const f of graph.fieldAccesses) if (f.symbol) edge('declaration', local('symbol', f.symbol), local('fieldAccess', f.id), f.confidence.tier);
+  for (const a of graph.allocations) if (a.symbol) edge('declaration', local('symbol', a.symbol), local('allocation', a.id), a.confidence.tier);
+
+  // Unresolved calls are unknowns on the view, not edges.
+  const unresolvedCalls = graph.callSites.filter((c) => !c.callee).length;
+  const reasons = [];
+  const schemaOnly = ENTITY_LISTS.filter((k) => graph.coverage[k].state === 'schema-only');
+  if (schemaOnly.length) reasons.push(`schema-only:${schemaOnly.join(',')}`);
+  if (unresolvedCalls) reasons.push(`unresolved-calls:${unresolvedCalls}`);
+  if ((graph.dynamicFeatures || []).length) reasons.push(`dynamic-features:${graph.dynamicFeatures.length}`);
+
+  return new IndexedGraphView({
+    graphKind: 'semantic', adapterVersion: SEMANTIC_ADAPTER_VERSION, repository: opts?.repository, graphDigest,
+    metadata: { schema: graph.schema, schemaVersion: graph.schemaVersion, producer: graph.producer ?? null, limits: graph.limits ?? [], unresolvedCalls },
+    completion: { status: reasons.length ? 'partial' : 'complete', reasons, coverage: graph.coverage },
+    nodes, edges,
+    reconstruct: () => graph,
+  });
+}

package/src/graph/crosswalk-builders.js

@@ -0,0 +1,152 @@
+//
+// crosswalk-builders.js: build the standard crosswalk mappings from registered
+// views. Every builder joins on facts the two graphs both carry and records
+// the join as evidence; none invents an identity.
+//
+//   finding -> semantic call site       file + line (location-exact)
+//   call site -> provenance witnesses   enclosing function (qid) + line
+//   witness -> projected flow           data element id
+//   projected node -> underlying sites  decision kind/category/coverage/externality
+//
+// Where a join cannot pin one target, the mapping lists ALL candidates
+// (one-to-many) and carries an `unknowns` entry. It never picks one silently.
+
+import { canonicalJson } from './refs.js';
+
+const stripLine = (qid) => String(qid).replace(/@\d+$/, '');
+const normFile = (f) => String(f ?? '').replace(/^\.\//, '').replace(/\\/g, '/');
+
+/**
+ * Join findings to semantic call sites by exact file and line.
+ * @returns {object[]} the mappings added
+ */
+export function mapFindingsToCallSites(crosswalk, findings, semantic) {
+  const byLoc = new Map();
+  for (const cs of semantic.entities('callSite')) {
+    const k = `${normFile(cs.native.file)}:${cs.native.line}`;
+    if (!byLoc.has(k)) byLoc.set(k, []);
+    byLoc.get(k).push(cs);
+  }
+  const added = [];
+  for (const f of findings.entities('finding')) {
+    const { file, line } = f.native;
+    if (!Number.isInteger(line) || !file) {
+      added.push(crosswalk.add({
+        type: 'finding-to-callsite', from: f.ref, to: [], unmapped: 'finding-has-no-file-and-line',
+        evidence: { method: 'file-line', grade: 'none', basis: 'the finding carries no integer line, so it cannot be located' },
+      }));
+      continue;
+    }
+    const hits = byLoc.get(`${normFile(file)}:${line}`) ?? [];
+    if (hits.length === 0) continue; // not a call-site finding; absence is visible as a trace gap
+    added.push(crosswalk.add({
+      type: 'finding-to-callsite', from: f.ref, to: hits.map((h) => h.ref), coarsens: hits.length > 1,
+      evidence: { method: 'file-line', grade: hits.length === 1 ? 'location-exact' : 'location-ambiguous', basis: `${normFile(file)}:${line}` },
+      unknowns: hits.length > 1 ? [{ kind: 'ambiguous-location', count: hits.length, reason: 'several call sites share this line; the finding names a line, not a call' }] : [],
+    }));
+  }
+  return added;
+}
+
+/**
+ * Join semantic call sites to provenance witnesses (pedges): same enclosing
+ * function and same line. The provenance scope is `<qid>@<line>`; the semantic
+ * symbol carries the qid without the line suffix.
+ */
+export function mapCallSitesToWitnesses(crosswalk, semantic, provenance) {
+  const witnessByKey = new Map();
+  for (const w of provenance.entities('pedge')) {
+    const k = `${stripLine(w.native.scope)}\u0000${w.native.line}`;
+    if (!witnessByKey.has(k)) witnessByKey.set(k, []);
+    witnessByKey.get(k).push(w);
+  }
+  const symQid = new Map(semantic.entities('symbol').map((s) => [s.localId, s.native.qid]));
+  const sitesPerKey = new Map();
+  const keyOf = (cs) => `${symQid.get(cs.native.caller)}\u0000${cs.native.line}`;
+  const sites = semantic.entities('callSite');
+  for (const cs of sites) sitesPerKey.set(keyOf(cs), (sitesPerKey.get(keyOf(cs)) ?? 0) + 1);
+  const added = [];
+  for (const cs of sites) {
+    const hits = witnessByKey.get(keyOf(cs)) ?? [];
+    if (hits.length === 0) continue;
+    const shared = sitesPerKey.get(keyOf(cs));
+    added.push(crosswalk.add({
+      type: 'callsite-to-witness', from: cs.ref, to: hits.map((h) => h.ref), coarsens: hits.length > 1 || shared > 1,
+      evidence: { method: 'scope-line', grade: shared > 1 ? 'location-ambiguous' : 'location-exact', basis: `${symQid.get(cs.native.caller)} line ${cs.native.line}` },
+      unknowns: shared > 1 ? [{ kind: 'shared-line', callSites: shared, reason: 'provenance records a line, not a call; these witnesses cannot be pinned to one of the call sites on that line' }] : [],
+    }));
+  }
+  return added;
+}
+
+/**
+ * Join provenance witnesses to the projected flows that carry their data
+ * element. A flow aggregates many witnesses (and many sites), so every mapping
+ * is flagged `coarsens`.
+ */
+export function mapWitnessesToFlows(crosswalk, provenance, dataflow) {
+  const flowsByDe = new Map();
+  for (const fl of dataflow.entities('flow')) {
+    for (const de of fl.native.dataElementIds || []) {
+      if (!flowsByDe.has(de)) flowsByDe.set(de, []);
+      flowsByDe.get(de).push(fl);
+    }
+  }
+  const added = [];
+  for (const w of provenance.entities('pedge')) {
+    const hits = flowsByDe.get(w.native.dataElementId) ?? [];
+    if (hits.length === 0) continue;
+    added.push(crosswalk.add({
+      type: 'witness-to-flow', from: w.ref, to: hits.map((h) => h.ref), coarsens: true,
+      evidence: { method: 'data-element', grade: 'identity-shared', basis: w.native.dataElementId },
+      unknowns: [{ kind: 'flow-granularity', reason: 'a projected flow aggregates every witness of its data element; the flow does not say which site this witness belongs to' }],
+    }));
+  }
+  return added;
+}
+
+const calleeText = (e) => {
+  if (!e || typeof e !== 'object') return null;
+  if (e.kind === 'ident') return e.name;
+  if (e.kind === 'member') { const o = calleeText(e.object); return o ? `${o}.${e.prop ?? '[]'}` : null; }
+  return null;
+};
+
+/**
+ * Map each projected (category-granular) dataflow node to the underlying call
+ * sites it stands for. `sites` is the sink-site list `buildDataFlowGraph`
+ * returns. A node with several sites maps one-to-many and is flagged `coarsens`;
+ * a site that no semantic call site matches is listed under `unknowns`.
+ */
+export function mapProjectedNodesToSites(crosswalk, dataflow, semantic, sites) {
+  const callSites = semantic.entities('callSite');
+  const added = [];
+  for (const n of dataflow.entities('node')) {
+    const node = n.native;
+    const matching = (sites || []).filter((s) => s.decision
+      && s.decision.kind === node.kind
+      && (s.decision.category ?? null) === (node.subtype ?? null)
+      && s.decision.coverageStatus === node.coverageStatus
+      && s.decision.externality === node.externality?.value
+      && canonicalJson(s.destination ?? null) === canonicalJson(node.destination ?? null));
+    if (matching.length === 0) continue;
+    const targets = new Map();
+    const unmapped = [];
+    for (const s of matching) {
+      const atLine = callSites.filter((c) => normFile(c.native.file) === normFile(s.file) && c.native.line === s.line);
+      const want = calleeText(s.calleeExpr);
+      const exact = want ? atLine.filter((c) => c.native.calleeText === want) : [];
+      const picked = exact.length ? exact : atLine;
+      if (picked.length === 0) unmapped.push({ file: s.file, line: s.line, reason: 'no semantic call site at this location' });
+      for (const c of picked) targets.set(c.localId, c);
+    }
+    const to = [...targets.values()].map((c) => c.ref);
+    const unknowns = unmapped.map((u) => ({ kind: 'unmapped-site', ...u }));
+    if (to.length === 0) continue;
+    added.push(crosswalk.add({
+      type: 'node-to-sites', from: n.ref, to, coarsens: to.length > 1, unknowns,
+      evidence: { method: 'decision-match', grade: to.length === 1 ? 'projection-exact' : 'projection-coarse', basis: `${node.kind}/${node.subtype ?? 'none'}: ${matching.length} sink site(s)` },
+    }));
+  }
+  return added;
+}

package/src/graph/crosswalk.js

@@ -0,0 +1,146 @@
+//
+// crosswalk.js: evidence-bearing identity mappings between graph layers
+// (DAG-06 R06.2, R06.5).
+//
+// A crosswalk never merges entities. It records "this entity in graph A
+// corresponds to these entities in graph B, by this method, with this
+// evidence". Every mapping is:
+//   - versioned (CROSSWALK_VERSION);
+//   - explicit about cardinality (`one-to-one`, `one-to-many`, or `none` with a
+//     stated reason), so a projection that coarsens many underlying sites into
+//     one projected node says so instead of pretending to be one-to-one;
+//   - evidence-bearing: method, grade and basis are required;
+//   - checked against the registry when one is supplied: a reference to a graph
+//     or entity that is not registered is rejected as DANGLING_REF.
+//
+// Mapping types and the graph layers each connects:
+//   finding-to-callsite   findings        -> semantic     (location join)
+//   callsite-to-witness   semantic        -> provenance   (scope + line join)
+//   witness-to-flow       provenance      -> dataflow     (data element join)
+//   node-to-sites         dataflow node   -> semantic     (a projected node's underlying call sites)
+//   identity              same layer      -> same layer   (the same entity under another reference)
+//
+// `identity` mappings are only legal inside ONE repository. Declaring two
+// entities in different repositories "the same" because their local ids match
+// is exactly the collision this module exists to prevent, and is rejected as
+// CROSS_REPO_ID_COLLISION.
+
+import { createHash } from 'node:crypto';
+import { GraphViewError, validateRef, refKey, canonicalJson } from './refs.js';
+
+export const CROSSWALK_VERSION = '1.0.0';
+
+export const MAPPING_TYPES = Object.freeze({
+  'finding-to-callsite': { from: { graphKind: 'findings', entityKind: 'finding' }, to: { graphKind: 'semantic', entityKind: 'callSite' } },
+  'callsite-to-witness': { from: { graphKind: 'semantic', entityKind: 'callSite' }, to: { graphKind: 'provenance', entityKind: 'pedge' } },
+  'witness-to-flow': { from: { graphKind: 'provenance', entityKind: 'pedge' }, to: { graphKind: 'dataflow', entityKind: 'flow' } },
+  'node-to-sites': { from: { graphKind: 'dataflow', entityKind: 'node' }, to: { graphKind: 'semantic', entityKind: 'callSite' } },
+  identity: { from: null, to: null },
+});
+
+const CARDINALITY = (n) => (n === 0 ? 'none' : n === 1 ? 'one-to-one' : 'one-to-many');
+
+function checkEnd(ref, want, label, type) {
+  const bad = validateRef(ref);
+  if (bad) throw new GraphViewError('BAD_REF', `${type} ${label}: ${bad}`, { ref });
+  if (want && (ref.graphKind !== want.graphKind || ref.entityKind !== want.entityKind)) {
+    throw new GraphViewError('BAD_MAPPING', `${type} ${label} must be a ${want.graphKind} ${want.entityKind}, got ${ref.graphKind} ${ref.entityKind}`, { ref });
+  }
+}
+
+export function createCrosswalk({ registry = null } = {}) {
+  const mappings = new Map();   // id -> record
+  const forward = new Map();    // refKey -> record[]
+  const reverse = new Map();    // refKey -> record[]
+  const push = (m, k, r) => { const a = m.get(k); if (a) a.push(r); else m.set(k, [r]); };
+
+  function add(spec) {
+    const type = spec?.type;
+    const desc = MAPPING_TYPES[type];
+    if (!desc) throw new GraphViewError('BAD_MAPPING', `unknown mapping type ${JSON.stringify(type)}`);
+    checkEnd(spec.from, desc.from, 'from', type);
+    if (!Array.isArray(spec.to)) throw new GraphViewError('BAD_MAPPING', `${type}: "to" is a list (empty with an unmapped reason when nothing matched)`);
+    for (const t of spec.to) checkEnd(t, desc.to, 'to', type);
+
+    const ev = spec.evidence;
+    if (!ev || typeof ev.method !== 'string' || !ev.method || typeof ev.grade !== 'string' || !ev.grade || typeof ev.basis !== 'string' || !ev.basis) {
+      throw new GraphViewError('BAD_MAPPING', `${type}: evidence needs { method, grade, basis }`);
+    }
+    const keys = spec.to.map(refKey);
+    if (new Set(keys).size !== keys.length) throw new GraphViewError('BAD_MAPPING', `${type}: duplicate targets in one mapping`);
+    if (spec.to.length === 0 && !spec.unmapped) throw new GraphViewError('BAD_MAPPING', `${type}: an empty mapping must say why in "unmapped"`);
+
+    if (type === 'identity') {
+      for (const t of spec.to) {
+        if (t.repository !== spec.from.repository) {
+          throw new GraphViewError('CROSS_REPO_ID_COLLISION', `identity mapping between repositories ${spec.from.repository} and ${t.repository} refused: matching local ids do not make two entities the same`, { from: spec.from, to: t });
+        }
+        if (t.entityKind !== spec.from.entityKind || t.graphKind !== spec.from.graphKind) {
+          throw new GraphViewError('BAD_MAPPING', 'identity maps an entity to the same kind of entity');
+        }
+      }
+    }
+    if (registry) {
+      for (const r of [spec.from, ...spec.to]) {
+        if (!registry.has(r)) throw new GraphViewError('DANGLING_REF', `${type}: ${r.graphKind} ${r.entityKind} ${r.localId} (repository ${r.repository}) is not in a registered graph`, { ref: r });
+      }
+    }
+
+    const id = `xwalk:${createHash('sha256').update(canonicalJson([type, refKey(spec.from), [...keys].sort(), ev.method])).digest('hex').slice(0, 16)}`;
+    if (mappings.has(id)) return mappings.get(id);
+    const record = Object.freeze({
+      id, version: CROSSWALK_VERSION, type, from: spec.from, to: Object.freeze([...spec.to]),
+      cardinality: CARDINALITY(spec.to.length),
+      coarsens: !!spec.coarsens,
+      evidence: Object.freeze({ ...ev }),
+      unknowns: Object.freeze([...(spec.unknowns ?? [])]),
+      unmapped: spec.unmapped ?? null,
+    });
+    mappings.set(id, record);
+    push(forward, refKey(record.from), record);
+    for (const k of keys) push(reverse, k, record);
+    return record;
+  }
+
+  const ofType = (list, type) => (type ? list.filter((m) => m.type === type) : list);
+
+  return {
+    version: CROSSWALK_VERSION,
+    add,
+    all: () => [...mappings.values()],
+    /** Mappings that start at `ref`. */
+    from: (ref, type) => ofType(forward.get(refKey(ref)) ?? [], type),
+    /** Mappings that end at `ref` (the reverse direction; many sources may share a target). */
+    to: (ref, type) => ofType(reverse.get(refKey(ref)) ?? [], type),
+
+    /**
+     * Follow a chain of mapping types from `start`. Returns every chain found
+     * and, for each step, which references had NO mapping (a gap is reported,
+     * never skipped). `evidence` lists every mapping used, so the join is
+     * traceable end to end.
+     */
+    trace(start, types, { maxChains = 1000 } = {}) {
+      let chains = [{ refs: [start], mappings: [] }];
+      const gaps = [];
+      let truncated = false;
+      for (const type of types) {
+        const next = [];
+        for (const c of chains) {
+          const last = c.refs[c.refs.length - 1];
+          const ms = this.from(last, type);
+          if (ms.length === 0) { gaps.push({ type, ref: last }); continue; }
+          for (const m of ms) {
+            if (m.to.length === 0) { gaps.push({ type, ref: last, unmapped: m.unmapped, mapping: m.id }); continue; }
+            for (const t of m.to) {
+              if (next.length >= maxChains) { truncated = true; break; }
+              next.push({ refs: [...c.refs, t], mappings: [...c.mappings, m.id] });
+            }
+          }
+        }
+        chains = next;
+      }
+      const used = new Set(chains.flatMap((c) => c.mappings));
+      return { start, types: [...types], chains, gaps, truncated, evidence: [...used].map((id) => mappings.get(id)) };
+    },
+  };
+}

package/src/graph/index.js

@@ -0,0 +1,15 @@
+// Typed graph views and identity crosswalks (DAG-06). See CLAUDE.md in this directory.
+export * from './refs.js';
+export * from './relations.js';
+export { IndexedGraphView, local, foreign, adjacencyCacheStats, clearAdjacencyCache } from './view.js';
+export { provenanceView, PROVENANCE_ADAPTER_VERSION } from './adapters/provenance.js';
+export { dataflowView, DATAFLOW_ADAPTER_VERSION } from './adapters/dataflow.js';
+export { semanticView, SEMANTIC_ADAPTER_VERSION } from './adapters/semantic.js';
+export { artifactView, ARTIFACT_ADAPTER_VERSION } from './adapters/artifact.js';
+export { crossRepoLinkView, findingsView, CROSSREPO_ADAPTER_VERSION, FINDINGS_ADAPTER_VERSION } from './adapters/crossrepo.js';
+export { createGraphRegistry, SUPPORTED_ADAPTER_MAJORS } from './registry.js';
+export { createCrosswalk, CROSSWALK_VERSION, MAPPING_TYPES } from './crosswalk.js';
+export {
+  mapFindingsToCallSites, mapCallSitesToWitnesses, mapWitnessesToFlows, mapProjectedNodesToSites,
+} from './crosswalk-builders.js';
+export { attributeObservation } from './observation.js';

package/src/graph/observation.js

@@ -0,0 +1,57 @@
+//
+// observation.js: attributing a runtime observation to the underlying sites of
+// a projected node (DAG-06 acceptance: "a projected node with several
+// underlying sites cannot falsely assign one runtime observation to every
+// site").
+//
+// A runtime observation is matched to a PROJECTED node (a destination, store or
+// queue). When that node stands for several call sites (a `node-to-sites`
+// mapping with more than one target), the observation says nothing about which
+// site produced it unless it carries its own discriminator. The result is:
+//
+//   attributed  exactly one site is justified: the node has a single site, or
+//               the observation names a site (`file` + `line`, or a call-site
+//               id) that matches exactly one candidate.
+//   ambiguous   several candidates remain. `attributedTo` is EMPTY, every
+//               candidate is listed, and no site receives the observation.
+//   unmatched   the observation names a site that is not one of the candidates.
+//
+// "Observed" is therefore a property of the projected node unless a site is
+// positively identified. An observation is never copied onto each site.
+
+import { refKey } from './refs.js';
+
+/**
+ * @param {object} crosswalk
+ * @param {object} registry
+ * @param {object} nodeRef  ref to the projected dataflow node the observation matched
+ * @param {{file?:string, line?:number, callSiteId?:string}} [observation]
+ */
+export function attributeObservation(crosswalk, registry, nodeRef, observation = {}) {
+  const mappings = crosswalk.from(nodeRef, 'node-to-sites');
+  const candidates = [];
+  const seen = new Set();
+  for (const m of mappings) for (const t of m.to) if (!seen.has(refKey(t))) { seen.add(refKey(t)); candidates.push(t); }
+  const base = { node: nodeRef, candidates, mappings: mappings.map((m) => m.id) };
+
+  if (candidates.length === 0) {
+    return { ...base, status: 'unmatched', attributedTo: [], reason: 'the projected node has no recorded underlying sites' };
+  }
+  const normFile = (f) => String(f ?? '').replace(/^\.\//, '');
+  const hasDiscriminator = observation.callSiteId || (observation.file && Number.isInteger(observation.line));
+  if (hasDiscriminator) {
+    const hit = candidates.filter((c) => {
+      if (observation.callSiteId) return c.localId === observation.callSiteId;
+      const n = registry.node(c).native;
+      return normFile(n.file) === normFile(observation.file) && n.line === observation.line;
+    });
+    if (hit.length === 1) return { ...base, status: 'attributed', attributedTo: hit, basis: 'observation-names-site' };
+    if (hit.length === 0) return { ...base, status: 'unmatched', attributedTo: [], reason: 'the observation names a site that is not one of the node\'s underlying sites' };
+    return { ...base, status: 'ambiguous', attributedTo: [], candidates: hit, reason: 'several call sites share the named location' };
+  }
+  if (candidates.length === 1) return { ...base, status: 'attributed', attributedTo: candidates, basis: 'sole-underlying-site' };
+  return {
+    ...base, status: 'ambiguous', attributedTo: [],
+    reason: `the projected node stands for ${candidates.length} sites and the observation does not say which one produced it`,
+  };
+}

package/src/graph/refs.js

@@ -0,0 +1,105 @@
+//
+// refs.js: the graph reference format (DAG-06 R06.2).
+//
+// A reference names ONE entity in ONE immutable graph:
+//   { v, graphKind, repository, graphDigest, entityKind, localId }
+//
+// The local id is only unique inside its graph, so it is never used alone as
+// a key. The repository identity and the graph digest are part of the
+// reference, which is what keeps two repositories with identical local ids
+// distinct and stops a stale reference from silently resolving against a
+// different version of the graph.
+//
+// Pure functions, no I/O.
+
+import { createHash } from 'node:crypto';
+
+export const REF_VERSION = 1;
+
+/** The graph layers that have an adapter. Every one keeps its own native schema. */
+export const GRAPH_KINDS = Object.freeze([
+  'provenance',        // PathStore pnode/pedge DAG
+  'dataflow',          // DataFlowGraph v1
+  'semantic',          // SemanticGraph v1
+  'artifact',          // artifact provenance graph
+  'cross-repo-links',  // declared CrossRepoLink records
+  'findings',          // scanner findings, as referenceable entities
+]);
+
+export class GraphViewError extends Error {
+  constructor(code, message, detail = {}) {
+    super(`${code}: ${message}`);
+    this.name = 'GraphViewError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const isNonEmpty = (v) => typeof v === 'string' && v.length > 0;
+
+/** Deterministic key-sorted JSON, the canonical form every digest here hashes. */
+export function canonicalJson(value) {
+  const canon = (v) => {
+    if (Array.isArray(v)) return v.map(canon);
+    if (v && typeof v === 'object') {
+      const o = {};
+      for (const k of Object.keys(v).sort()) if (v[k] !== undefined) o[k] = canon(v[k]);
+      return o;
+    }
+    return v;
+  };
+  return JSON.stringify(canon(value));
+}
+
+export function digestOf(value) {
+  return createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+
+/**
+ * Build a reference object. Throws GraphViewError('BAD_REF') on a missing
+ * component: a reference with a blank part is never constructed.
+ */
+export function makeRef({ graphKind, repository, graphDigest, entityKind, localId }) {
+  const ref = { v: REF_VERSION, graphKind, repository, graphDigest, entityKind, localId };
+  const bad = validateRef(ref);
+  if (bad) throw new GraphViewError('BAD_REF', bad, { ref });
+  return Object.freeze(ref);
+}
+
+/** @returns {string|null} a problem description, or null when the reference is well formed */
+export function validateRef(ref) {
+  if (!ref || typeof ref !== 'object' || Array.isArray(ref)) return 'a reference is an object';
+  if (ref.v !== REF_VERSION) return `unsupported reference version ${JSON.stringify(ref.v)} (supported: ${REF_VERSION})`;
+  if (!GRAPH_KINDS.includes(ref.graphKind)) return `unknown graph kind ${JSON.stringify(ref.graphKind)}`;
+  for (const f of ['repository', 'graphDigest', 'entityKind', 'localId']) {
+    if (!isNonEmpty(ref[f])) return `${f} is required`;
+  }
+  return null;
+}
+
+/** The identity of the graph a reference points into (no entity part). */
+export function graphIdentityKey(ref) {
+  return [ref.graphKind, ref.repository, ref.graphDigest].map(encodeURIComponent).join('|');
+}
+
+/** Stable string form; also the map key used by every index. */
+export function refKey(ref) {
+  const bad = validateRef(ref);
+  if (bad) throw new GraphViewError('BAD_REF', bad, { ref });
+  return `gref${ref.v}|${[ref.graphKind, ref.repository, ref.graphDigest, ref.entityKind, ref.localId].map(encodeURIComponent).join('|')}`;
+}
+
+export function parseRef(text) {
+  if (typeof text !== 'string') throw new GraphViewError('BAD_REF', 'a reference string is required');
+  const parts = text.split('|');
+  const m = /^gref(\d+)$/.exec(parts[0] || '');
+  if (!m || parts.length !== 6) throw new GraphViewError('BAD_REF', 'malformed reference string');
+  let decoded;
+  try { decoded = parts.slice(1).map(decodeURIComponent); } catch { throw new GraphViewError('BAD_REF', 'malformed escape in reference string'); }
+  const [graphKind, repository, graphDigest, entityKind, localId] = decoded;
+  return makeRef({ graphKind, repository, graphDigest, entityKind, localId, v: Number(m[1]) });
+}
+
+export function sameRef(a, b) {
+  return refKey(a) === refKey(b);
+}