@clear-capabilities/agentic-security-scanner 0.195.23 → 0.195.25

package/src/lineage/engine.js

@@ -74,6 +74,13 @@ function isV2(ctx) {
 // the derivation path of the level that emitted it (the innermost stamp
 // wins, because an inner wrapper's fields are already on the hop when the
 // outer wrapper sees it).
+/** `JSON.parse` / `JSON.stringify` (GA-03.3): the one call pair the resolver treats as structure-preserving. */
+function isJsonRoundTrip(callee) {
+  if (typeof callee === 'string') return callee === 'JSON.parse' || callee === 'JSON.stringify';
+  return !!callee && callee.kind === 'member' && (callee.prop === 'parse' || callee.prop === 'stringify')
+    && callee.object?.kind === 'ident' && callee.object.name === 'JSON';
+}
+
 function sub(ctx, seg, stamp) {
   if (!isV2(ctx)) return ctx;
   const derivation = deriveChild(ctx.derivation, seg);
@@ -610,6 +617,19 @@ export function resolveExprIdentities(state, expr, ctx) {
           return { flat, byPath, widened: false };
         }
       }
+      // GA-03.3 (0.195.25): a JSON round trip is structure-PRESERVING.
+      // `JSON.stringify(v)` carries exactly v's fields (serialized) and
+      // `JSON.parse(s)` yields exactly the fields s was serialized from, so
+      // both forward the first argument's `{flat, byPath, widened}`
+      // unchanged, the way `assign-expr` forwards its source: the field a
+      // queue consumer reads off `JSON.parse(m.Body)` keeps the identity the
+      // producer put under that key instead of collapsing to the whole
+      // record's flat union. The argument's own recursion emits its hops;
+      // nothing is recorded for the call itself (there is no new value).
+      // The replacer/reviver/space arguments never carry the value.
+      if (isJsonRoundTrip(expr.callee) && (expr.args ?? []).length >= 1) {
+        return resolveExprIdentities(state, expr.args[0], sub(ctx, 'a0'));
+      }
       const flat = new Set();
       // Hotfix (found during Sub-project E1's design spike; see
       // DESIGN_GRAPH_BUILDER.md §11): an unresolved method call's RECEIVER
@@ -923,6 +943,18 @@ function step(node, stateIn, widenings, ctx) {
           }
         }
       }
+      // Known, disclosed gap (GA-03.1, 0.195.24, measured): a bare call
+      // statement is never resolved through `ctx.resolveCallSummary`, so a
+      // sink INSIDE the callee (`emit(logger, req.body.card_number)` with
+      // `logger.info(v)` in emit) never sees the argument's identity; the
+      // value is an escape here and nothing more. Resolving it was tried
+      // and reverted in 0.195.24: the extra callee analysis consumes a
+      // summary context per call site, and under a tight context cap that
+      // degrades a later resolution to an empty summary (the §13.2a hazard
+      // of DESIGN_PATH_PROVENANCE.md, in the unsound direction), moving
+      // seven pinned provenance measurements. Closing it needs the cap to
+      // exempt bare-call contexts or a separate budget; pinned as a gap by
+      // test/lineage/seeding-across-calls.test.js (IP/2).
       return { state: stateIn, returnFact: null };
     }
 
@@ -1068,7 +1100,18 @@ export function analyzeFunctionFieldIdentity(fn, entryState, ctx) {
           recordHop: stepRecord,
         }
       : ctx;
-    const { state: out, returnFact } = step(node, incoming, widenings, stepCtx);
+    let { state: out, returnFact } = step(node, incoming, widenings, stepCtx);
+    // GA-03.1 (0.195.24): `after-node` seeds (source-seeding.js, SEED_KINDS).
+    // A call-shaped source assigned to a variable produces its identity in
+    // the TARGET once this node has run; the assignment's own strong update
+    // has already cleared the target, so this is a plain add, idempotent on
+    // a worklist revisit. Keyed by `(scope, nid)` so the same hook serves a
+    // callee analysed through the call-summary resolver. No hop is recorded
+    // here: the first read of the target creates the path node, which then
+    // has no in-edges and reconstructs as an origin, exactly as an entry
+    // seed's first read does.
+    const after = ctx?.seedAfterNode ? ctx.seedAfterNode(scope, nid) : undefined;
+    if (after) for (const s of after) out = addIdentity(out, s.path, s.id);
     if (returnFact && returnFact.size > 0) {
       // Union onto any existing fact for this node rather than pushing a
       // new array entry every visit — see Fix 2 in the final whole-branch

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
@@ -131,7 +132,7 @@ import { classifyHandling } from './handling-analyzer.js';
 import { emptyGraphEnvelope } from './schema.js';
 import { emptyProtection, aggregateVerdicts } from './protection.js';
 import * as ids from './ids.js';
-import { planSeeds, seedEntryStateFactory, exprRoots, walkExpr } from './source-seeding.js';
+import { planSeeds, seedEntryStateFactory, seedAfterNodeFactory, exprRoots, walkExpr } from './source-seeding.js';
 import { RECIPIENT_FACT_FIELDS } from './recipient-profile.js';
 import { pathEvidenceEnabled, evaluatePathEvidence, summarizeFlowEvidence } from './path-evidence.js';
 import { sinkFamilyOf } from './control-credit.js';
@@ -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,18 +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),
-    ...(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
@@ -480,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 ?? {} });
@@ -491,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' }),
@@ -568,11 +670,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,
@@ -583,9 +696,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: [],
@@ -600,7 +719,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
@@ -652,7 +770,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;
@@ -743,13 +861,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
@@ -772,7 +895,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;
@@ -809,6 +932,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
@@ -1167,11 +1293,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 }
@@ -1192,5 +1324,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,19 @@ 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 } : {}),
       generatedAt: opts.deterministic ? undefined : new Date().toISOString(),
       perFile: opts.perFile,
       parseFailures: opts.parseFailures,

package/src/lineage/lineage-source-catalog.js

@@ -0,0 +1,143 @@
+//
+// lineage-source-catalog.js — JavaScript data collection points that are
+// lineage sources but NOT taint sources (GA plan, GA-03.1: "address
+// source-category omissions without broadening the main taint catalog
+// incorrectly").
+//
+// Four of the fourteen reachable `SOURCE_CATEGORIES` had no `language: 'js'`
+// entry in `dataflow/catalog.js` at all: `cli-argument` (only `py-sys-argv`
+// and the argparse entries), `http-upload` (only Django and Symfony),
+// `storage-read` (only `py-open-read` and the C `read`/`fread`/`fgets`
+// entries) and `user-input` (only `py-input`, `gets`, `scanf`). The lineage
+// corpus therefore could not mint a source node for any of them from a
+// JavaScript fixture, and the four corpus entries that name them were
+// written in Python syntax on purpose, as a disclosed limitation.
+//
+// Why these entries live HERE and not in `dataflow/catalog.js`'s `CATALOG`:
+// that catalog is the taint engine's source list, and every entry in it
+// becomes an attacker-controlled input for every SAST and taint finding the
+// engine emits. A file's contents (`fs.readFileSync`) and a console prompt
+// (`prompt()`, `readlineSync.question()`) are places personal data ENTERS a
+// program, which is what a lineage graph records, but treating them as
+// attacker-controlled would turn every configuration read into a taint
+// source and flood the SAST output with findings nobody asked for. The
+// Data Flow Explorer already keeps a second, isolated catalog for the same
+// reason (`dataflow/privacy-catalog.js`, never merged into `CATALOG`); this
+// module follows that precedent on the source side. `test/lineage/
+// lineage-source-catalog.test.js` pins that `dataflow/catalog.js`'s own
+// `matchSource` returns null for every shape listed here, so adding an
+// entry here can never widen the taint engine by accident.
+//
+// Reuse boundary: imports nothing from `dataflow/`. The matcher below is a
+// deliberately small structural match over the parser's expression shape
+// (`ident`/`member`/`call`), not a copy of `catalog.js`'s index machinery;
+// an entry that needs receiver types, keyword arguments or a language family
+// other than JavaScript belongs in the main catalog, with the taint
+// consequences weighed there.
+
+import { reclassifySource } from './source-registry.js';
+
+const JS_FILE = /\.(?:[cm]?js|jsx|tsx?)$/i;
+
+/**
+ * Each entry mirrors the main catalog's source shape (`kind`, `id`,
+ * `language`, `framework`, `match`, `label`, `provenance`) so
+ * `reclassifySource` reads it unchanged: `provenance` is the key the
+ * registry's `PROVENANCE_MAP` resolves to a `SOURCE_CATEGORIES` value.
+ * `lineageOnly: true` is the marker a reader greps for; nothing consults it.
+ */
+export const LINEAGE_SOURCE_CATALOG = Object.freeze([
+  {
+    kind: 'source', id: 'js-process-argv', language: 'js', framework: 'node', lineageOnly: true,
+    match: { type: 'member', object: 'process', prop: 'argv' }, label: 'process.argv', provenance: 'cli',
+    why: 'a positional command-line argument; the value is whatever the operator typed, not attacker-controlled in the taint sense, so it is a collection point for lineage only',
+  },
+  {
+    kind: 'source', id: 'js-multer-req-file', language: 'js', framework: 'express', lineageOnly: true,
+    match: { type: 'member', object: 'req', prop: 'file' }, label: 'req.file', provenance: 'upload',
+    why: 'the single uploaded file multer attaches to the request (name, type, buffer, path)',
+  },
+  {
+    kind: 'source', id: 'js-multer-req-files', language: 'js', framework: 'express', lineageOnly: true,
+    match: { type: 'member', object: 'req', prop: 'files' }, label: 'req.files', provenance: 'upload',
+    why: 'the uploaded files multer attaches to the request, keyed by field name',
+  },
+  {
+    kind: 'source', id: 'js-fs-readFileSync', language: 'js', framework: 'node', lineageOnly: true,
+    match: { type: 'call', callee: 'readFileSync' }, label: 'fs.readFileSync()', provenance: 'file-read',
+    why: 'the contents of a file; the callback form `fs.readFile(p, cb)` delivers its contents to a callback and is not seeded (its path argument is already a sink in the main catalog)',
+  },
+  {
+    kind: 'source', id: 'js-window-prompt', language: 'js', framework: 'browser', lineageOnly: true,
+    match: { type: 'call', callee: 'prompt', bare: true }, label: 'prompt()', provenance: 'stdin',
+    why: 'text a person typed into the browser prompt dialog; only the bare global, never `x.prompt()` (inquirer and friends return a promise of an answers object)',
+  },
+  {
+    kind: 'source', id: 'js-readline-sync-question', language: 'js', framework: 'node', lineageOnly: true,
+    match: { type: 'call', callee: 'question', receiver: 'readlineSync' }, label: 'readlineSync.question()', provenance: 'stdin',
+    why: 'text a person typed at the console; the readline module\'s own `rl.question(q, cb)` delivers the answer to a callback and is not seeded',
+  },
+]);
+
+/** The receiver chain of a member-call callee, outermost first (`a.b.c()` -> ['a', 'b']). */
+function receiverSegments(callee) {
+  const segs = [];
+  let cur = callee && callee.kind === 'member' ? callee.object : null;
+  let depth = 0;
+  while (cur && depth++ < 8) {
+    if (cur.kind === 'ident') { segs.unshift(cur.name); break; }
+    if (cur.kind === 'member') { if (typeof cur.prop === 'string') segs.unshift(cur.prop); cur = cur.object; continue; }
+    break;
+  }
+  return segs;
+}
+
+function calleeName(callee) {
+  if (!callee) return null;
+  if (typeof callee === 'string') return callee.slice(callee.lastIndexOf('.') + 1);
+  if (callee.kind === 'ident') return callee.name ?? null;
+  if (callee.kind === 'member') return typeof callee.prop === 'string' ? callee.prop : null;
+  return null;
+}
+
+function entryMatches(entry, expr) {
+  const m = entry.match;
+  if (m.type === 'member') {
+    return expr.kind === 'member' && expr.object?.kind === 'ident' && expr.object.name === m.object && expr.prop === m.prop;
+  }
+  if (m.type === 'call') {
+    if (expr.kind !== 'call') return false;
+    if (calleeName(expr.callee) !== m.callee) return false;
+    if (m.bare) return expr.callee && expr.callee.kind === 'ident';
+    if (m.receiver) return receiverSegments(expr.callee).includes(m.receiver);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * The lineage-only counterpart of `dataflow/catalog.js`'s `matchSource`:
+ * returns the first catalog entry whose `match` fits `expr`, or null.
+ * Gated to JavaScript and TypeScript files (an entry here is JavaScript by
+ * construction); a missing `file` is permissive, matching `matchSource`.
+ * Never throws on a malformed expression.
+ */
+export function matchLineageSource(expr, file) {
+  if (!expr || typeof expr !== 'object') return null;
+  if (file && !JS_FILE.test(file)) return null;
+  for (const entry of LINEAGE_SOURCE_CATALOG) {
+    if (entryMatches(entry, expr)) return entry;
+  }
+  return null;
+}
+
+/** The registry decision for every entry, computed once: proves at load time that each `provenance` resolves. */
+export const LINEAGE_SOURCE_DECISIONS = Object.freeze(Object.fromEntries(
+  LINEAGE_SOURCE_CATALOG.map((e) => {
+    const d = reclassifySource(e);
+    if (!d || !d.category || d.coverageStatus === 'unsupported') {
+      throw new Error(`lineage-source-catalog: ${e.id} has a provenance (${e.provenance}) the source registry cannot classify`);
+    }
+    return [e.id, d];
+  }),
+));