@clear-capabilities/agentic-security-scanner 0.195.24 → 0.195.26

package/src/lineage/graph-builder.js

@@ -111,8 +111,9 @@
 // entry point), it does not wrap it.
 
 import { matchSinkOrSanitizer } from '../dataflow/catalog.js';
-import { matchPrivacySink } from '../dataflow/privacy-catalog.js';
+import { matchPrivacySink, PRIVACY_SINK_CATALOG } from '../dataflow/privacy-catalog.js';
 import { matchOrmWrite } from '../dataflow/orm-write-catalog.js';
+import { collectBoundaryEndpoints, planBoundaryJoins, queueCommandOf, MAX_BOUNDARY_ROUNDS } from './boundary-join.js';
 // Milestone 2, Sub-project G, increment 1 (FR-408/AC-09): `isSinkPermitted`/
 // `permittingRules` are pure, vocabulary-agnostic functions (no hardcoded
 // sink-name check anywhere in that module — confirmed by direct read) that
@@ -195,6 +196,19 @@ function resolveSinkAtCallSite(calleeExpr, file) {
   };
 }
 
+/**
+ * GA-03.3 (0.195.25): the registry decision for an AWS SDK v3 send command
+ * (`queueCommandOf` in boundary-join.js). Resolves through the privacy
+ * catalog's queue entry named by the command table, so the node is the same
+ * `queue` decision the v2 `sendMessage`/`publish` shapes get; never through
+ * the general catalog, whose bare `send` entry is a different sink.
+ */
+function resolveQueueCommandSite(cmd) {
+  const entry = PRIVACY_SINK_CATALOG.find((e) => e.id === cmd.entry);
+  if (!entry) return null;
+  return { entry, decision: reclassifyPrivacySink(entry), ambiguity: null, queueCommand: cmd.command };
+}
+
 /**
  * Milestone 2, Sub-project E, increment 1 (ORM-write sink recognition,
  * `docs/superpowers/plans/2026-08-31-data-flow-explorer-m2-subproject-e1-plan.md`).
@@ -345,7 +359,17 @@ export function enumerateSinkSites(callGraph) {
   for (const fn of callGraph.functions.values()) {
     for (const [nid, node] of Object.entries(fn.cfg?.nodes ?? {})) {
       if (node.kind === 'call' && node.callee) {
-        const r = resolveSinkAtCallSite(node.callee, fn.file);
+        // GA-03.3 (0.195.25): the AWS SDK v3 command shape,
+        // `client.send(new SendMessageCommand(input))`. The general catalog's
+        // bare `send` entry (a koa-send path sink) used to claim this call as
+        // an unresolved file sink; it is a queue publish, resolved through the
+        // privacy catalog's own queue entry so the registry decision is the
+        // same one `sqs.sendMessage(input)` gets. A RECEIVE command is a read,
+        // not a sink: the site is skipped here and becomes a boundary
+        // consumer (boundary-join.js) instead.
+        const cmd = queueCommandOf(node.callee, node.args ?? []);
+        if (cmd && cmd.role === 'receive') continue;
+        const r = cmd ? resolveQueueCommandSite(cmd) : resolveSinkAtCallSite(node.callee, fn.file);
         if (r) {
           sites.push({ file: fn.file, qid: fn.qid, nodeId: nid, line: node.line ?? null, calleeExpr: node.callee, args: node.args ?? [], ...r });
           // Milestone 2, Sub-project E, increment 3: queue/topic identity
@@ -356,7 +380,7 @@ export function enumerateSinkSites(callGraph) {
           // only the queue category needs).
           if (r.decision.category === 'queue') {
             const site = sites[sites.length - 1];
-            site.queueDetail = extractQueueDetail(node.args ?? []);
+            site.queueDetail = extractQueueDetail(cmd ? [cmd.input] : (node.args ?? []));
           }
         }
         // Milestone 2, Sub-project E, increment 1: ORM-write recognition,
@@ -414,6 +438,27 @@ function calleeDescriptor(calleeExpr) {
 }
 const calleeDisplay = (d) => (!d ? null : d.type === 'member-call' ? `${d.object}.${d.method}` : d.callee);
 
+/**
+ * GA-03.3: the coverage record for handoff joins, the same for the builder's
+ * own sketch and coverage.js's finished ledger. Disabled builds say so;
+ * nothing is counted that was not attempted.
+ */
+export function boundaryCoverage(boundaries) {
+  if (!boundaries) return { enabled: false };
+  return {
+    enabled: true,
+    rounds: boundaries.rounds, maxRounds: MAX_BOUNDARY_ROUNDS, truncated: boundaries.truncated,
+    producers: boundaries.endpoints.producers, consumers: boundaries.endpoints.consumers,
+    joins: boundaries.joins.length,
+    joinedFields: boundaries.joins.reduce((n, j) => n + j.fields.length, 0),
+    declared: boundaries.joins.filter((j) => j.provenance === 'manual').length,
+    discovered: boundaries.joins.filter((j) => j.provenance === 'code').length,
+    unjoined: boundaries.unjoined.map((u) => ({ side: u.side, kind: u.kind, file: u.file, line: u.line, reason: u.reason })),
+    gaps: boundaries.gaps.length,
+    note: 'Every join is modeled from a declared contract or a literal identity both sides name; none is an observed message or row.',
+  };
+}
+
 const nodeLabel = (kind, category, reason) => (category
   ? `${category} (${kind})`
   : `unsupported ${kind}: ${String(reason).split(';')[0].slice(0, 80)}`);
@@ -446,20 +491,57 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     ...(opts.signal ? { signal: opts.signal } : {}),
     ...(opts.deadline === undefined ? {} : { deadline: opts.deadline }),
   });
-  const hops = [];
-  const analysis = runFieldIdentityAnalysis(callGraph, {
-    recordHop: (h) => hops.push(h),
-    seedEntryState: seedEntryStateFactory(seeds),
-    // GA-03.1 (0.195.24): call-shaped sources assigned to a variable.
-    ...(seedAfterNodeFactory(seeds) ? { seedAfterNode: seedAfterNodeFactory(seeds) } : {}),
-    ...(opts.maxContextsPerFn === undefined ? {} : { maxContextsPerFn: opts.maxContextsPerFn }),
-    ...(opts.maxIterations === undefined ? {} : { maxIterations: opts.maxIterations }),
-    // DAG-03: provenance correlation version 2 (off unless requested).
-    ...(opts.correlationVersion === undefined ? {} : { correlationVersion: opts.correlationVersion }),
-    ...(opts.signal ? { signal: opts.signal } : {}),
-    ...(opts.deadline === undefined ? {} : { deadline: opts.deadline }),
-    ...(opts.onProgress ? { onProgress: opts.onProgress } : {}),
-  });
+  const runAnalysis = (seedsNow) => {
+    const hopsNow = [];
+    const afterNode = seedAfterNodeFactory(seedsNow);
+    const analysisNow = runFieldIdentityAnalysis(callGraph, {
+      recordHop: (h) => hopsNow.push(h),
+      seedEntryState: seedEntryStateFactory(seedsNow),
+      // GA-03.1 (0.195.24): call-shaped sources assigned to a variable.
+      ...(afterNode ? { seedAfterNode: afterNode } : {}),
+      ...(opts.maxContextsPerFn === undefined ? {} : { maxContextsPerFn: opts.maxContextsPerFn }),
+      ...(opts.maxIterations === undefined ? {} : { maxIterations: opts.maxIterations }),
+      // DAG-03: provenance correlation version 2 (off unless requested).
+      ...(opts.correlationVersion === undefined ? {} : { correlationVersion: opts.correlationVersion }),
+      ...(opts.signal ? { signal: opts.signal } : {}),
+      ...(opts.deadline === undefined ? {} : { deadline: opts.deadline }),
+      ...(opts.onProgress ? { onProgress: opts.onProgress } : {}),
+    });
+    return { hops: hopsNow, analysis: analysisNow };
+  };
+  let { hops, analysis } = runAnalysis(seeds);
+  // Sink sites are enumerated once, here, because the boundary rounds below
+  // need the producer sites before the projection does. Pure over the call
+  // graph, so the order change is not observable.
+  const { sites, nonStatementSites } = enumerateSinkSites(callGraph);
+  // GA-03.3 (0.195.25): cross-service handoffs (boundary-join.js). Opt-in
+  // (`opts.boundaries.enabled`); a build that omits it is byte-identical to
+  // the build before this existed. A round plans the consumer seeds the
+  // current hop stream supports and, when it minted any, re-runs the field
+  // analysis so a chain of handoffs resolves; the round count is bounded and
+  // a still-productive last round is reported as truncated, never read as
+  // convergence.
+  let boundaries = null;
+  if (opts.boundaries && opts.boundaries.enabled) {
+    const endpoints = collectBoundaryEndpoints(callGraph, sites);
+    const contracts = Array.isArray(opts.boundaries.contracts) ? opts.boundaries.contracts : [];
+    const minted = new Set();
+    const joinsById = new Map();
+    boundaries = { enabled: true, rounds: 0, truncated: false, seeds: 0, joins: [], unjoined: endpoints.unjoined, gaps: [], endpoints: { producers: endpoints.producers.length, consumers: endpoints.consumers.length } };
+    for (let round = 0; round <= MAX_BOUNDARY_ROUNDS; round++) {
+      const r = planBoundaryJoins({ endpoints, hops, contracts, callGraph, minted });
+      for (const j of r.joins) if (!joinsById.has(j.joinId) || j.fields.length) joinsById.set(j.joinId, j);
+      boundaries.unjoined = r.unjoined;
+      boundaries.gaps = r.gaps;
+      if (!r.seeds.length) break;
+      if (round === MAX_BOUNDARY_ROUNDS) { boundaries.truncated = true; break; }
+      seeds.push(...r.seeds);
+      boundaries.seeds += r.seeds.length;
+      boundaries.rounds += 1;
+      ({ hops, analysis } = runAnalysis(seeds));
+    }
+    boundaries.joins = [...joinsById.values()].sort((a, b) => (a.joinId < b.joinId ? -1 : 1));
+  }
   const store = new PathStore({}, { correlationVersion: opts.correlationVersion });
   store.addHops(hops);
   // DAG-07 R07.2: an analysis unit that hit its budget has no hop
@@ -482,6 +564,10 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
   for (const u of analysisCompletion.incomplete) {
     store.markTruncated(u.qid, u.context, u.reasons[0] ?? 'analysis-incomplete');
   }
+  if (boundaries && boundaries.truncated) {
+    analysisCompletion.boundaries = { rounds: boundaries.rounds, maxRounds: MAX_BOUNDARY_ROUNDS, truncated: true };
+    if (analysisCompletion.status === 'complete') analysisCompletion.status = 'partial';
+  }
 
   const cfgByQid = new Map();
   for (const fn of callGraph.functions.values()) cfgByQid.set(fn.qid, { fn, nodes: fn.cfg?.nodes ?? {} });
@@ -493,6 +579,20 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     if (!seedSitesByDe.has(s.dataElementId)) seedSitesByDe.set(s.dataElementId, []);
     seedSitesByDe.get(s.dataElementId).push(s);
   }
+  // GA-03.3: one data element can now be seeded in more than one function
+  // (its collection point and every consumer a handoff carried it into).
+  // The seed a path starts from is the one in the function the path's
+  // terminal node lives in; the first seed is the fallback for a path whose
+  // terminal is not a seeded location (unchanged behaviour when there is one
+  // seed per element, which is every build without boundaries).
+  const seedForPath = (p) => {
+    const cands = seedSitesByDe.get(p.dataElementId);
+    if (!cands || cands.length < 2) return seedByDe.get(p.dataElementId);
+    const scope = store.getNode(p.terminal?.nodeId)?.scope ?? store.getNode(p.hops?.[0]?.fromNodeId)?.scope ?? null;
+    return cands.find((s) => s.qid === scope) ?? cands[0];
+  };
+  const siteByKey = new Map();
+  for (const site of sites) siteByKey.set(`${site.qid}|${site.nodeId}`, site);
 
   const graph = emptyGraphEnvelope({
     graphId: ids.graphId({ repository, commit: opts.commit ?? 'uncommitted', configHash: opts.configHash ?? 'default' }),
@@ -502,6 +602,14 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     // module ever passed `undefined`/omitted the key entirely).
     generatedAt: opts.generatedAt ?? '1970-01-01T00:00:00.000Z',
   });
+  // GA-03.7 (0.195.26): the revision the graph was built from, when the
+  // caller knows it (a scan passes the repository head). A consumer can then
+  // refuse a graph built from another revision (`loadSignedGraph`'s
+  // `expectRevision`). Absent when no commit was given, so a build without
+  // one is byte-identical to before.
+  if (typeof opts.commit === 'string' && opts.commit) {
+    graph.scope.revision = { commit: opts.commit, worktreeDirty: typeof opts.worktreeDirty === 'boolean' ? opts.worktreeDirty : null };
+  }
 
   const nodesById = new Map();
   const edgesById = new Map();
@@ -570,11 +678,22 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     decisionsByNodeId.get(id).push({ kind, category, coverageStatus, externality });
     return n;
   };
-  const sourceNodeFor = (s) => mintNode({
-    kind: 'source', category: s.category, coverageStatus: s.coverageStatus, externality: s.externality,
-    coverageReason: s.reason, subtypeKey: s.category ?? `unsupported-source:${s.entryId}`,
-    lifecycleStages: ['collection'],
-  });
+  // GA-03.3: a seed a handoff minted has no collection point of its own; its
+  // source node IS the producer's sink node (the queue or the store), so the
+  // graph reads as one chain, HTTP to queue to store to HTTP response, with
+  // the handoff visible on the edge. The producer site always exists (a join
+  // is planned from a site in `sites`); the fallback below is defensive.
+  const sourceNodeFor = (s) => {
+    if (s.boundary) {
+      const psite = siteByKey.get(`${s.boundary.producer.qid}|${s.boundary.producer.nodeId}`);
+      if (psite) return sinkNodeFor(psite);
+    }
+    return mintNode({
+      kind: 'source', category: s.category, coverageStatus: s.coverageStatus, externality: s.externality,
+      coverageReason: s.reason, subtypeKey: s.category ?? `unsupported-source:${s.entryId}`,
+      lifecycleStages: ['collection'],
+    });
+  };
   const sinkNodeFor = (site) => mintNode({
     kind: site.decision.kind, category: site.decision.category,
     coverageStatus: site.decision.coverageStatus, externality: site.decision.externality,
@@ -585,9 +704,15 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     storeDetail: site.storeDetail ?? null,
     queueDetail: site.queueDetail ?? null,
   });
-  const mintDataElement = (s) => {
-    let d = deById.get(s.dataElementId);
+  const mintDataElement = (seedIn) => {
+    let d = deById.get(seedIn.dataElementId);
     if (!d) {
+      // GA-03.3: an element is named by its collection point, never by the
+      // key a handoff carried it under (`{contact: email}` is still the
+      // element `email` at the consumer). The first non-boundary seed of
+      // the element is that collection point; a boundary seed is the
+      // fallback only when nothing else minted the element.
+      const s = (seedSitesByDe.get(seedIn.dataElementId) ?? []).find((x) => !x.boundary) ?? seedIn;
       d = {
         id: s.dataElementId, name: s.canonicalName, aliases: [], declaredType: null,
         dataClasses: s.dataClasses, aiContexts: [], sourceLocations: [],
@@ -602,7 +727,6 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
     return d;
   };
 
-  const { sites, nonStatementSites } = enumerateSinkSites(callGraph);
   // E4's FR-203 closure hook (DESIGN_GRAPH_BUILDER.md §9.4 item 5b): a
   // caller may substitute an adjusted decision for a site — e.g.
   // coverage.js's `resolveSiteDecision`, which reclassifies a sink whose
@@ -654,7 +778,7 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
       if (r.truncated) stats.truncatedQueries += 1;
       stats.pathsEnumerated += r.enumeratedPathCount;
       for (const p of r.paths) {
-        const seed = seedByDe.get(p.dataElementId);
+        const seed = seedForPath(p);
         if (!seed) continue;
         connected = true;
         stats.pathsProjected += 1;
@@ -745,13 +869,18 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
             id: edgeIdStr, from: src.id, to: snk.id, relationship: 'data_flow',
             fieldMappings: [{ fromPath, toPath, dataElementIds: [de.id], mappingType, transformationIds: sortedT }],
             protocol: { name: 'in-process', destinationResolution: site.destination?.resolutionStatus ?? 'unknown' },
-            boundaryCrossings: [],
+            // GA-03.3: an edge from a handoff seed records the crossing it
+            // rests on. The connection is modeled (a declared contract or a
+            // literal identity both sides name), never observed.
+            boundaryCrossings: seed.boundary
+              ? [{ kind: seed.boundary.kind, identity: seed.boundary.identity, joinId: seed.boundary.joinId, contractId: seed.boundary.contractId, basis: seed.boundary.basis, modeledInput: true, observed: false }]
+              : [],
             // Milestone 2, Sub-project F, increment 1 (FR-304): which
-            // mechanism discovered this edge. Every edge minted here today
-            // is genuinely code-derived — this is an unconditional, honest
-            // literal, never a guess (see schema.js's EDGE_PROVENANCE_VALUES
-            // comment for the full rationale).
-            provenance: 'code',
+            // mechanism discovered this edge. An edge minted from code is
+            // `code`; an edge a boundary contract declared is `manual`
+            // (GA-03.3). Never a guess (see schema.js's
+            // EDGE_PROVENANCE_VALUES comment for the full rationale).
+            provenance: seed.boundary ? seed.boundary.provenance : 'code',
             // Milestone 2, Sub-project B, increment 2 (FR-401):
             // `opts.resolveTransitProtection(site) -> {verdict, evidenceGrade}
             // | undefined`, applied at this exact point — the same block
@@ -774,7 +903,7 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
         // key by design and therefore never splits a flow.
         const flowKey = [src.id, snk.id, de.id, p.shape, g.grade, sortedT.join(',')].join('|');
         if (!groupsByFlowKey.has(flowKey)) groupsByFlowKey.set(flowKey, []);
-        groupsByFlowKey.get(flowKey).push({ p, g, src, snk, de, edgeIdStr, sortedT, site, unattributed, truncated: r.truncated, truncationReasons: r.truncationReasons, result: r });
+        groupsByFlowKey.get(flowKey).push({ p, g, src, snk, de, seed, edgeIdStr, sortedT, site, unattributed, truncated: r.truncated, truncationReasons: r.truncationReasons, result: r });
       }
     }
     site.connected = connected;
@@ -811,6 +940,9 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
       ...(site.ambiguity && site.ambiguity.resolvedBy === 'plurality'
         ? [`sink category ambiguous at ${site.file}:${site.line}: also matches ${site.ambiguity.alternatives.join(', ')}`]
         : []),
+      ...(group[0].seed?.boundary
+        ? [`crosses a ${group[0].seed.boundary.kind} handoff (${group[0].seed.boundary.provenance === 'manual' ? `contract ${group[0].seed.boundary.contractId}` : `literal identity ${group[0].seed.boundary.identity}`}) that is modeled, not observed: no message or row was seen`]
+        : []),
     ])].sort();
     // Milestone 2, Sub-project D, increment 1 (FR-403): computed once,
     // here, from this flow's own representative reconstructed path — never
@@ -1169,11 +1301,17 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
       ...(store.correlationVersion() === 2 ? { correlationVersion: 2 } : null),
     },
     ...(analysisCompletion.status === 'complete' ? {} : { analysisCompletion }),
+    ...(boundaries ? { boundaries: boundaryCoverage(boundaries) } : {}),
   };
   graph.limitations = [
     'Protection verdicts are not assessed in Milestone 1: every edge carries not_assessed/none on all three dimensions.',
     'Policy verdicts are not evaluated in Milestone 1.',
     'External destinations are not resolved (FR-202 is Milestone 2); protocol.destinationResolution is "unknown" on every edge.',
+    // GA-03.3: only a build that opted in says anything here, so a build
+    // that did not is byte-identical to the build before joins existed.
+    ...(boundaries
+      ? [`Cross-service handoffs are joined from a declared boundary contract or from the same literal queue or collection identity on both sides (${boundaries.joins.length} join(s), ${boundaries.unjoined.length} endpoint(s) left unjoined with a reason); every join is modeled from code, never an observed message or row.`]
+      : []),
   ];
   graph.scanHealth = analysisCompletion.status === 'complete'
     ? { status: 'complete', reason: 'lineage-graph-builder', analysisCompletion }
@@ -1194,5 +1332,5 @@ export function buildDataFlowGraph(callGraph, opts = {}) {
   }
   graph.taxonomy = { version: '1.0.0', source: 'built-in + CONFIDENTIAL extension' };
 
-  return { graph, store, hops, analysisCompletion, seeds, unseedable, sites, nonStatementSites, degraded, stats, decisionsByNodeId };
+  return { graph, store, hops, analysisCompletion, seeds, unseedable, sites, nonStatementSites, degraded, stats, decisionsByNodeId, boundaries };
 }

package/src/lineage/index.js

@@ -70,6 +70,7 @@ import { loadObservations } from './observation-store.js';
 // (which owns only the REMOTE side).
 import { validateCrossRepoLink, CROSS_REPO_LINKS_FILENAME } from './cross-repo-link.js';
 import { contributeNixConfigLineage } from './nix-view.js';
+import { BOUNDARY_CONTRACTS_FILENAME } from './boundary-contract.js';
 import { adaptCallGraphForLineage } from './haskell-view.js';
 
 // A small, LOCAL, tolerant loader for the operator-declared
@@ -83,6 +84,31 @@ import { adaptCallGraphForLineage } from './haskell-view.js';
 // degrades to an empty/partial array with a console warning naming the
 // count skipped, mirroring `loadRecipientConfig`'s own per-entry
 // discipline.
+/**
+ * GA-03.3: the DAG-08 contracts file, `[]` when absent or malformed (the
+ * parse error is printed, never thrown). Read directly and absence taken
+ * from the read's own error, so there is no existence check before the open.
+ */
+function _loadBoundaryContracts(scanRoot) {
+  if (!scanRoot) return [];
+  const fp = statePath(scanRoot, BOUNDARY_CONTRACTS_FILENAME);
+  let raw;
+  try {
+    raw = fs.readFileSync(fp, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return [];
+    console.error(`agentic-security: cannot read boundary contracts file (${fp}); no declared handoffs will be joined (${e.message})`);
+    return [];
+  }
+  try {
+    const doc = JSON.parse(raw);
+    return Array.isArray(doc) ? doc : Array.isArray(doc && doc.contracts) ? doc.contracts : [];
+  } catch (e) {
+    console.error(`agentic-security: bad JSON in boundary contracts file (${fp}); no declared handoffs will be joined (${e.message})`);
+    return [];
+  }
+}
+
 function _loadCrossRepoLinkRecords(filePath) {
   let raw;
   try {
@@ -262,8 +288,21 @@ export function buildLineageGraph(callGraph, opts = {}) {
     // Haskell is rewritten into a lineage VIEW (source reads become seedable member reads, sinks become
     // statement-level calls); every other language, and the shared call graph itself, are untouched.
     const lineageCallGraph = adaptCallGraphForLineage(callGraph);
+    // GA-03.3: cross-service handoff joins, opt-in (`opts.boundaries`,
+    // from AGENTIC_SECURITY_LINEAGE_BOUNDARIES=1 in engine.js). The
+    // operator's DAG-08 boundary contracts are read once here, from the
+    // same state directory `dataflow contracts` reads, existence-gated like
+    // every other config load in this function; a malformed file is a
+    // recorded failure of the join step (an empty contract list with the
+    // error named), never a thrown scan.
+    const boundaries = opts.boundaries && opts.boundaries.enabled
+      ? { enabled: true, contracts: opts.boundaries.contracts ?? _loadBoundaryContracts(opts.scanRoot) }
+      : undefined;
     const built = buildGraphWithCoverage(lineageCallGraph, {
       repository: opts.repository,
+      ...(boundaries ? { boundaries } : {}),
+      // GA-03.7: the scanned revision, recorded in `graph.scope.revision` and in the graph id.
+      ...(typeof opts.commit === 'string' && opts.commit ? { commit: opts.commit, worktreeDirty: opts.worktreeDirty } : {}),
       generatedAt: opts.deterministic ? undefined : new Date().toISOString(),
       perFile: opts.perFile,
       parseFailures: opts.parseFailures,

package/src/lineage/source-seeding.js

@@ -272,6 +272,13 @@ export function planSeeds(callGraph, { repository, maxSeeds, maxNodes, signal, d
 
 const MAX_ALIAS_ROUNDS = 4;
 
+/** `JSON.parse(x)` / `JSON.stringify(x)` → x (one level); anything else unchanged. */
+function unwrapJsonRoundTrip(e) {
+  if (e && e.kind === 'call' && e.callee && e.callee.kind === 'member' && (e.callee.prop === 'parse' || e.callee.prop === 'stringify')
+    && e.callee.object && e.callee.object.kind === 'ident' && e.callee.object.name === 'JSON' && Array.isArray(e.args) && e.args.length) return e.args[0];
+  return e;
+}
+
 /** `(fn, fnSeeds, mint)`: see the comment at the call site in `planSeeds`. */
 function extendThroughAliases(fn, fnSeeds, mint) {
   const nodes = Object.entries(fn.cfg?.nodes ?? {});
@@ -293,7 +300,10 @@ function extendThroughAliases(fn, fnSeeds, mint) {
     for (const [, node] of nodes) {
       if (node.kind !== 'assign' || typeof node.target !== 'string' || node.target.includes('.') || node.target.includes('*')) continue;
       if (aliases.has(node.target)) continue;
-      const r = resolve(accessPathOf(node.source));
+      // GA-03.3: a JSON round trip keeps the container's structure (the
+      // same rule engine.js applies), so `const s = JSON.stringify(req.body)`
+      // and `const back = JSON.parse(s)` are aliases of the container too.
+      const r = resolve(accessPathOf(unwrapJsonRoundTrip(node.source)));
       if (!r) continue;
       aliases.set(node.target, r);
       changed = true;

package/src/posture/dag-commands.js

@@ -79,7 +79,7 @@ async function loadProgram(root) {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * agentic-security dataflow view [path] [--node <id> [--direction in|out|both] [--relations a,b] [--origins a,b]] [--output <file>]
+ * agentic-security dataflow view [path] [--node <id> [--direction in|out|both] [--relations a,b] [--origins a,b]] [--expect-revision <sha|HEAD>] [--output <file>]
  * Read-only over the signed lineage graph. Without --node it reports the view identity, counts, completion and the SCC
  * condensation of the data-flow relation. With --node it lists the neighbours the filter allows.
  */
@@ -95,7 +95,18 @@ export async function cmdDataflowView(args) {
   if (f.node === undefined && (f.direction || f.relations || f.origins)) { err(`${who}: --direction, --relations and --origins apply to --node.`); return 2; }
 
   const { loadSignedGraph } = await import('../server/graph-loader.js');
-  const loaded = loadSignedGraph(root);
+  // GA-03.7: `--expect-revision <sha|HEAD>` refuses a graph built from another revision (or from none).
+  let expectRevision = null;
+  if (f['expect-revision'] !== undefined) {
+    if (typeof f['expect-revision'] !== 'string' || !f['expect-revision']) { err(`${who}: --expect-revision needs a commit or HEAD.`); return 2; }
+    if (f['expect-revision'] === 'HEAD') {
+      const { getRepoState } = await import('./provenance/git-evidence.js');
+      const st = getRepoState(root);
+      if (!st || !st.head) { err(`${who}: --expect-revision HEAD needs a git repository at ${root}.`); return 2; }
+      expectRevision = st.head;
+    } else expectRevision = f['expect-revision'];
+  }
+  const loaded = loadSignedGraph(root, { expectRevision });
   if (!loaded.ok) { err(`${who}: ${loaded.message}`); return 1; }
   const { dataflowView, GraphViewError } = await import('../graph/index.js');
   const { computeScc, verifyScc } = await import('../graph/scc.js');
@@ -107,6 +118,8 @@ export async function cmdDataflowView(args) {
     schema: 'agentic-security/graph-view-report@1',
     maturity: 'preview',
     identity: view.identity,
+    revision: loaded.graph.scope && loaded.graph.scope.revision ? loaded.graph.scope.revision : null,
+    expectedRevision: expectRevision,
     metadata: view.metadata(),
     viewCompletion: view.completion(),
     note: 'A view is a read-only lens over the signed graph. An absent edge means the model has no such edge, not that the software has none.',

package/src/posture/provenance/git-evidence.js

@@ -1,4 +1,5 @@
 import * as cp from 'node:child_process';
+import { STATE_DIR_NAME } from '../state-dir.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { hardenGitArgs, hardenGitEnv } from '../../util/git-hardening.js';
@@ -95,6 +96,26 @@ export function getRemoteUrl(scanRoot) {
   return r.ok ? r.stdout.trim() : null;
 }
 
+/**
+ * Whether the working tree has changes OUTSIDE the given path prefixes (default: the scanner's own state
+ * directory). `getRepoState().dirty` counts the scanner's own untracked state directory as dirty, which would make the
+ * lineage graph's recorded revision flip between two scans of an unchanged tree merely because the first
+ * scan created that directory. Null when not a git repository or when git fails.
+ */
+export function worktreeDirtyExcluding(scanRoot, ignorePrefixes = [`${STATE_DIR_NAME}/`]) {
+  if (!isGitRepo(scanRoot)) return null;
+  const r = _run(scanRoot, ['status', '--porcelain', '--untracked-files=all']);
+  if (!r.ok) return null;
+  for (const line of r.stdout.split('\n')) {
+    if (!line.trim()) continue;
+    const p = line.slice(3).replace(/^"|"$/g, '');
+    const renamedTo = p.includes(' -> ') ? p.split(' -> ')[1] : p;
+    if (ignorePrefixes.some((pre) => p.startsWith(pre) || renamedTo.startsWith(pre))) continue;
+    return true;
+  }
+  return false;
+}
+
 export function getRepoState(scanRoot) {
   if (!isGitRepo(scanRoot)) return null;
   const head = _run(scanRoot, ['rev-parse', 'HEAD']);

package/src/server/graph-loader.js

@@ -19,7 +19,7 @@ import { verifyLastScan } from '../posture/integrity.js';
 
 /**
  * @param {string} scanRoot
- * @returns {{ok:true, graph:object} | {ok:false, reason:'missing'|'unsigned'|'tampered'|'malformed', message:string}}
+ * @returns {{ok:true, graph:object} | {ok:false, reason:'missing'|'unsigned'|'tampered'|'malformed'|'wrong-revision', message:string}}
  *
  * Four, and only four, distinct failure reasons — each with its own clear
  * message so an operator knows exactly what to do next:
@@ -36,7 +36,7 @@ import { verifyLastScan } from '../posture/integrity.js';
  *                  valid JSON. Should not happen from a normal scan; the
  *                  file may be corrupted on disk after signing.
  */
-export function loadSignedGraph(scanRoot) {
+export function loadSignedGraph(scanRoot, { expectRevision = null } = {}) {
   const graphPath = statePath(scanRoot, 'lineage-graph.json');
   const sigPath = graphPath + '.sig';
 
@@ -86,6 +86,23 @@ export function loadSignedGraph(scanRoot) {
     };
   }
 
+  // GA-03.7 (0.195.26): wrong-revision refusal. A caller that knows which
+  // revision it expects (`dataflow view --expect-revision`) gets a graph
+  // only when the graph records that revision; a graph that records none
+  // cannot prove it and is refused for the same reason, never served on
+  // the hope that it matches.
+  if (expectRevision) {
+    const have = graph && graph.scope && graph.scope.revision ? graph.scope.revision.commit : null;
+    if (have !== expectRevision) {
+      return {
+        ok: false,
+        reason: 'wrong-revision',
+        message: have
+          ? `Lineage graph at ${graphPath} was built from revision ${have}, not the expected ${expectRevision}. Re-run the scan on the expected revision.`
+          : `Lineage graph at ${graphPath} records no revision, so it cannot be shown to match the expected ${expectRevision}. Re-run the scan inside the repository (AGENTIC_SECURITY_LINEAGE_DEEP=1) so the graph records its revision.`,
+      };
+    }
+  }
   return { ok: true, graph };
 }