@clear-capabilities/agentic-security-scanner 0.144.0 → 0.147.0

package/src/lineage/handling-analyzer.js

@@ -0,0 +1,168 @@
+//
+// handling-analyzer.js — Milestone 2, Sub-project D ("handling analyzer +
+// FR-307 control-credit"), increment 1.
+//
+// FR-403's single-path handling TAXONOMY classifier — see
+// DESIGN_HANDLING_ANALYZER.md for the full design record: the exact
+// `transform-catalog.js` `kind` -> `schema.js` `HANDLING_VALUES` mapping
+// table, the load-bearing naming note distinguishing `flow.handling` (this
+// module's output) from `protection.js`'s own `PROTECTION_DIMENSIONS`
+// `handling` dimension (a different field, a different vocabulary, a
+// different question), and everything explicitly deferred (FR-307's
+// multi-path control-credit rule, `aggregate`'s own `'aggregated'` verdict,
+// any UI/display concern).
+//
+// Reuse boundary: imports ONLY `recognizeTransformation` from
+// `./transform-catalog.js` and `exprRoots`/`walkExpr` from
+// `./source-seeding.js` — both already-shipped, read-only consumers, per
+// this package's established isolation convention. Never
+// `dataflow/engine.js`, never `dataflow/summaries.js`, never
+// `dataflow/catalog.js`/`dataflow/privacy-catalog.js` directly.
+//
+// A pure, one-path-at-a-time classifier. `classifyHandling(path, callGraph)`
+// takes ONE `path-query.js#reconstructPaths` result path — the caller picks
+// which; this module never iterates multiple paths to one sink, that is
+// FR-307's job, explicitly deferred to D2 — and never throws on malformed
+// input.
+
+import { recognizeTransformation } from './transform-catalog.js';
+import { exprRoots, walkExpr } from './source-seeding.js';
+
+/**
+ * The `transform-catalog.js` `kind` -> FR-403 `HANDLING_VALUES` mapping
+ * (DESIGN_HANDLING_ANALYZER.md §2). Five kinds map to their own protective
+ * handling state (`mask`/`redact`/`hash`/`tokenize`/`encrypt`); five more
+ * (`decrypt`/`encode`/`decode`/`truncate`/`normalize`) map to `'unknown'`
+ * because none of them is itself a PROTECTIVE handling state for FR-403's
+ * purposes — decoding/truncating/normalizing doesn't protect a field, and
+ * a `decrypt` immediately before a sink is actively the OPPOSITE of
+ * protection. `aggregate` ALSO maps to `'unknown'` here, for a different,
+ * disclosed reason: `HANDLING_VALUES` carries its own `'aggregated'`
+ * value, but awarding it needs shape-level reasoning about a WHOLE
+ * collection that a single-hop, single-path classifier cannot do soundly —
+ * deferred to D2/later, never faked from a hop-level recognition alone.
+ * `custom`/`unknown` never appear as keys here because
+ * `recognizeTransformation` never emits them as a `kind`
+ * (`transform-catalog.js`'s own documented, load-time-enforced contract).
+ */
+const KIND_TO_HANDLING = Object.freeze({
+  mask: 'masked',
+  redact: 'redacted',
+  hash: 'hashed',
+  tokenize: 'tokenized',
+  encrypt: 'encrypted',
+  decrypt: 'unknown',
+  encode: 'unknown',
+  decode: 'unknown',
+  truncate: 'unknown',
+  normalize: 'unknown',
+  aggregate: 'unknown',
+});
+
+/** The honest empty answer: no hop on this path yielded a recognized
+ * transform. Frozen and shared — this module never mutates its own
+ * return values. */
+const RAW_RESULT = Object.freeze({ handling: 'raw', recognizedTransform: null, hopIndex: null });
+
+/**
+ * Mirrors `graph-builder.js`'s own private (unexported) `calleeDescriptor`
+ * helper. Deliberately NOT imported from there — see
+ * DESIGN_HANDLING_ANALYZER.md §3 for why a third copy of this ~10-line
+ * shape was chosen over introducing a `graph-builder.js` <->
+ * `handling-analyzer.js` module cycle (this module is wired INTO
+ * `graph-builder.js`, the reverse direction). Never throws; returns `null`
+ * for anything that cannot become a `transform-catalog.js` descriptor.
+ */
+function calleeDescriptorOf(calleeExpr) {
+  if (typeof calleeExpr === 'string') return { type: 'call', callee: calleeExpr };
+  if (!calleeExpr || typeof calleeExpr !== 'object') return null;
+  if (calleeExpr.kind === 'ident' && typeof calleeExpr.name === 'string') return { type: 'call', callee: calleeExpr.name };
+  if (calleeExpr.kind === 'member' && typeof calleeExpr.prop === 'string') {
+    const obj = calleeExpr.object && calleeExpr.object.kind === 'ident' ? calleeExpr.object.name : null;
+    return obj ? { type: 'member-call', object: obj, method: calleeExpr.prop } : { type: 'call', callee: calleeExpr.prop };
+  }
+  return null;
+}
+
+/**
+ * Every `{kind: 'call', ...}` expression reachable from one CFG node, in
+ * expression-tree order — mirrors `graph-builder.js`'s own per-hop
+ * transformation-extraction loop exactly (`exprRoots`/`walkExpr` over the
+ * node, plus the node's OWN call when the node itself is `kind: 'call'` —
+ * `exprRoots` only ever yields a call NODE's `callee`/`args`, never a
+ * `{kind:'call'}` shape for the node itself, so that case needs the same
+ * explicit unshift `graph-builder.js` already uses). This is what makes an
+ * `assign`-kind CFG node whose `.source` IS a call (`const maskedPan =
+ * maskCard(cardNumber);`) resolvable too, not just a bare call statement —
+ * see DESIGN_HANDLING_ANALYZER.md §3 item 2 for why that distinction is
+ * load-bearing for this increment's own required AC-02 fixture. Defensive:
+ * a malformed `node` yields `[]`, never throws.
+ */
+function callsAt(node) {
+  if (!node || typeof node !== 'object') return [];
+  const calls = [];
+  for (const root of exprRoots(node)) walkExpr(root, (e) => { if (e && typeof e === 'object' && e.kind === 'call') calls.push(e); });
+  if (node.kind === 'call' && node.callee) calls.unshift({ kind: 'call', callee: node.callee, args: node.args ?? [] });
+  return calls;
+}
+
+/**
+ * FR-403's single-path handling classifier. `path` is one
+ * `path-query.js#reconstructPaths` result path (the caller picks which —
+ * this module never iterates multiple paths to one sink, per FR-307's own
+ * deferred multi-path control-credit rule). `callGraph` is the same
+ * `scanner/src/ir/callgraph.js#buildCallGraph`-shaped object (a real
+ * `Map` at `.functions`) `graph-builder.js` already consumes, or an
+ * equivalent hand-built fixture exposing the same shape.
+ *
+ * Walks `path.hops` in the SOURCE-TO-SINK order `path-query.js` already
+ * materializes paths in. For each hop, resolves
+ * `callGraph.functions.get(hop.scope)?.cfg?.nodes?.[hop.siteNodeId]`
+ * defensively — never throws on a missing/malformed lookup, mirroring
+ * every other lineage module's defensiveness — and, when that CFG node
+ * yields one or more call expressions (via `callsAt`, above), tries
+ * `recognizeTransformation` on each in expression order. Returns the FIRST
+ * recognized transform found walking from source to sink.
+ *
+ * @param {object} path a `reconstructPaths` result path
+ * @param {object} callGraph `{functions: Map<qid, {cfg: {nodes}}>, ...}`
+ * @returns {{handling: string, recognizedTransform: object|null, hopIndex: number|null}}
+ *   `handling` is always a `schema.js` `HANDLING_VALUES` member.
+ *   `recognizedTransform` is `recognizeTransformation`'s own decision
+ *   object (kind/reversibility/algorithm/confidence/evidence), unmodified,
+ *   when one was found — else `null`. `hopIndex` is the index into
+ *   `path.hops` the transform was found at, else `null`. When no hop
+ *   yields a recognized transform, returns
+ *   `{handling: 'raw', recognizedTransform: null, hopIndex: null}` —
+ *   never a guess.
+ */
+export function classifyHandling(path, callGraph) {
+  const hops = Array.isArray(path?.hops) ? path.hops : [];
+  const fns = callGraph && callGraph.functions && typeof callGraph.functions.get === 'function' ? callGraph.functions : null;
+  if (!fns) return RAW_RESULT;
+
+  for (let i = 0; i < hops.length; i++) {
+    const hop = hops[i];
+    if (!hop || typeof hop !== 'object') continue;
+    const fn = fns.get(hop.scope);
+    const node = fn?.cfg?.nodes?.[hop.siteNodeId];
+    if (!node) continue;
+    for (const call of callsAt(node)) {
+      const descriptor = calleeDescriptorOf(call.callee);
+      if (!descriptor) continue;
+      const rec = recognizeTransformation(descriptor);
+      if (!rec) continue;
+      // Defensive fallback only — every non-fallback `TRANSFORM_KINDS`
+      // value `recognizeTransformation` can actually emit is a key in
+      // `KIND_TO_HANDLING` above (11 kinds, both tables measured against
+      // the same live `transform-catalog.js`), so `?? 'unknown'` is never
+      // exercised by real catalog output today. Kept rather than omitted
+      // so a future catalog kind this table hasn't been updated for fails
+      // safe (an honest `'unknown'`) instead of writing `undefined` onto
+      // `flow.handling`.
+      const handling = KIND_TO_HANDLING[rec.kind] ?? 'unknown';
+      return { handling, recognizedTransform: rec, hopIndex: i };
+    }
+  }
+  return RAW_RESULT;
+}

package/src/lineage/ids.js

@@ -0,0 +1,349 @@
+//
+// Stable-ID spec for DataFlowGraph v1 (PRD 10.1: "Stable within the
+// repository/commit; independent of visual layout"). Mirrors the shape
+// scanner/src/posture/stable-id.js already established for findings:
+// sha256 over a canonicalized, pipe-joined material string, truncated to
+// a fixed hex length, prefixed by the entity kind. Same rationale — a
+// content hash survives reordering and re-emission, unlike an
+// incrementing counter.
+
+import * as crypto from 'node:crypto';
+
+const ID_HEX_LEN = 12;
+
+function _hash(material, len = ID_HEX_LEN) {
+  return crypto.createHash('sha256').update(material).digest('hex').slice(0, len);
+}
+
+function _canon(parts) {
+  return parts.map((p) => (p === undefined || p === null ? '' : String(p))).join('|');
+}
+
+/** PRD 10.2's literal example shape: `dfg:<repository>:<commit>:<configuration-hash>`. */
+export function graphId({ repository, commit, configHash } = {}) {
+  const repo = repository || 'unknown-repo';
+  const c = commit || 'uncommitted';
+  const cfg = configHash || 'default';
+  return `dfg:${repo}:${c}:${cfg}`;
+}
+
+/** discriminatorParts should include enough of {system, location, destination} to be unique within the graph. */
+export function nodeId(kind, discriminatorParts = []) {
+  return `node:${kind}:${_hash(_canon([kind, ...discriminatorParts]))}`;
+}
+
+/** discriminatorParts should include the owning service/schema so the same field name in two services never collides (PRD 10.4). */
+export function dataElementId(canonicalName, discriminatorParts = []) {
+  return `data:${_hash(_canon([canonicalName, ...discriminatorParts]))}`;
+}
+
+export function edgeId(fromId, toId, relationship, discriminatorParts = []) {
+  return `edge:${_hash(_canon([fromId, toId, relationship, ...discriminatorParts]))}`;
+}
+
+/**
+ * A node in `path-store.js`'s provenance DAG (Sub-project C, increment 4;
+ * DESIGN_PATH_PROVENANCE.md §14.2/§14.5). `pnode:`/`pedge:` are deliberately
+ * distinct prefixes from `node:`/`edge:` above: a provenance node is NOT a
+ * `DataFlowGraph v1` node, and `validate.js`'s id-prefix regexes must never
+ * be able to confuse the two namespaces.
+ *
+ * Object-argument, not this file's usual positional-plus-discriminatorParts
+ * form (a deliberate, narrow divergence — `graphId` is the in-file
+ * precedent) — the discriminator is wide enough that a positional array is
+ * exactly the shape a future field addition would silently omit from.
+ */
+export function provenanceNodeId(
+  { kind, scope, context, path, siteNodeId, dataElementId },
+  discriminatorParts = [],
+) {
+  return `pnode:${kind}:${_hash(_canon([kind, scope, context, path, siteNodeId, dataElementId, ...discriminatorParts]))}`;
+}
+
+/**
+ * An edge in `path-store.js`'s provenance DAG: one (in-half, out-half) pair
+ * at one join group (§14.5). The discriminator carries the SITE (`scope`,
+ * `context`, `siteNodeId`) as well as both endpoint ids — two structurally
+ * identical hops at two different program points are two materially
+ * different edges (FR-305), each needing its own `line` for display and
+ * §9.2's hop-ordering lever; omitting `siteNodeId` would silently collide
+ * them into one edge carrying one arbitrary line. It also carries both
+ * halves' `kind`/`subKind` and their reason strings — the
+ * `flagship-fixture.mjs` lesson (see this package's own CLAUDE.md row)
+ * applied deliberately: under-specifying a content-hash discriminator is a
+ * silent merge. NOT in the discriminator: `syntacticPath` and `line`
+ * (display material), edge `annotations[]`, and `ambiguousCorrelation`
+ * (both are functions of the group and the endpoints already in the id).
+ */
+export function provenanceEdgeId(
+  {
+    fromNodeId, toNodeId, dataElementId,
+    scope, context, siteNodeId,
+    inKind, inSubKind, outKind, outSubKind,
+    widenReasons = [], lossReasons = [],
+  },
+  discriminatorParts = [],
+) {
+  return `pedge:${_hash(_canon([
+    fromNodeId, toNodeId, dataElementId,
+    scope, context, siteNodeId,
+    inKind, inSubKind, outKind, outSubKind,
+    [...widenReasons].sort().join(','), [...lossReasons].sort().join(','),
+    ...discriminatorParts,
+  ]))}`;
+}
+
+/**
+ * A reconstructed path (Sub-project C, increment 5;
+ * DESIGN_PATH_PROVENANCE.md §15.6). `pnode:`/`pedge:`'s own header left this
+ * name deliberately unclaimed (§14.5: "the thing C5 reconstructs *is* a
+ * path, and it will plausibly want that name") — increment 5 claims it,
+ * with a `ppath:` prefix joining the same family. A reconstructed path is
+ * not a `DataFlowGraph v1` entity either, so `validate.js` needs no change.
+ *
+ * The discriminator is the EDGE id SEQUENCE, never the node id sequence
+ * (§15.6/FR-305 — two paths can share a node sequence while differing in
+ * the edges that join it, e.g. two assignments at two different program
+ * points, and that difference must not be hidden by dedup) — order matters
+ * for a path, unlike a node/edge discriminator's set-like fields, so
+ * `edgeIds` is NOT sorted before hashing. `startNodeId` is strictly
+ * redundant today (a path always has at least one hop, so the last edge id
+ * already determines it) but is kept per §14.5's own lesson: over-specifying
+ * a content hash costs nothing, under-specifying one is a silent merge.
+ */
+export function pathId({ startNodeId, edgeIds }, discriminatorParts = []) {
+  return `ppath:${_hash(_canon([startNodeId, ...edgeIds, ...discriminatorParts]))}`;
+}
+
+/**
+ * dataElementIds is treated as a SET (sorted before hashing) — a flow
+ * carrying {card_number, cvv} has one identity regardless of the order the
+ * builder discovered them in. `discriminatorParts` is the escape hatch for
+ * two flows sharing source/sink/fields that must still be distinct paths
+ * (e.g. a masked branch vs. a raw branch to the same log sink).
+ */
+export function flowId(sourceNodeId, sinkNodeId, dataElementIds = [], discriminatorParts = []) {
+  const sorted = [...dataElementIds].sort();
+  return `flow:${_hash(_canon([sourceNodeId, sinkNodeId, ...sorted, ...discriminatorParts]))}`;
+}
+
+export function transformationId(anchorId, calleeName, discriminatorParts = []) {
+  return `transform:${_hash(_canon([anchorId, calleeName, ...discriminatorParts]))}`;
+}
+
+export function evidenceId(claim, location, discriminatorParts = []) {
+  return `evidence:${_hash(_canon([claim, location, ...discriminatorParts]))}`;
+}
+
+/**
+ * An ObligationMapping record's id (FR-504 §7.12, sub-project 6a) — NOT a
+ * DataFlowGraph v1 entity, so validate.js's id-prefix regexes and
+ * json-schema-parity.test.js's $defs audit need zero change, mirroring
+ * why provenanceNodeId/provenanceEdgeId are prefixed outside the
+ * node:/edge:/flow: family. Discriminated by (framework, frameworkVersion,
+ * requirementId, graphId, graphDigest) — graphId ALONE is not enough:
+ * real callers never supply graphId's own configHash component (only
+ * `graph-builder.js` reads it, via `opts.configHash ?? 'default'`, and
+ * nothing calls it with one), so every real scan at one commit produces
+ * the identical graphId regardless of the graph's actual CONTENT — found
+ * by this sub-project's own final whole-branch review, reproduced live:
+ * two records against genuinely different base graphs (same repo/commit,
+ * different analyzer output) collided onto one id without graphDigest in
+ * the material. graphDigest is the field §10.10 already requires every
+ * extension record to carry precisely so it can be distinguished from a
+ * same-graphId, different-content graph — this discriminator is what
+ * makes that requirement actually load-bearing for uniqueness, not just
+ * a payload field alongside an otherwise-collidable id.
+ */
+export function obligationId(
+  { framework, frameworkVersion, requirementId, graphId, graphDigest },
+  discriminatorParts = [],
+) {
+  return `obligation:${_hash(_canon([framework, frameworkVersion, requirementId, graphId, graphDigest, ...discriminatorParts]))}`;
+}
+
+/**
+ * A RecipientProfile record's id (FR-506 §7.12, "Third-Party and
+ * Cross-Border Intelligence", Milestone 4) — NOT a DataFlowGraph v1
+ * entity, mirrors obligationId's own precedent exactly (a real,
+ * stable-ID'd extension record that is deliberately not a base-graph
+ * entity). Discriminated by (graphId, graphDigest, recipientKey) —
+ * graphDigest is required in the discriminator for the identical reason
+ * obligationId's own comment gives (no real caller supplies graphId's own
+ * configHash component, so graphId alone never distinguishes two
+ * same-commit graphs with genuinely different content); recipientKey is
+ * the stable string a later task keys one recipient by (e.g. a
+ * normalized hostname or provider id), so two profiles for the same
+ * recipient across two different graphs never collide, and two DIFFERENT
+ * recipients within the same graph never collide either.
+ */
+export function recipientProfileId(
+  { graphId, graphDigest, recipientKey },
+  discriminatorParts = [],
+) {
+  return `recipient:${_hash(_canon([graphId, graphDigest, recipientKey, ...discriminatorParts]))}`;
+}
+
+/**
+ * A DecisionStory record's id (M4 deliverable #7, FR-501 §14, DFG-035) —
+ * NOT a DataFlowGraph v1 entity, mirrors obligationId's own precedent
+ * exactly (a real, stable-ID'd extension record that is deliberately not
+ * a base-graph entity). Discriminated by (graphDigest, audienceMode,
+ * scopeQuery) rather than graphId alone, for the identical reason
+ * obligationId's own comment gives: two stories over the same graphId but
+ * genuinely different graph CONTENT (or a different filter/audience
+ * scope) must not collide onto one id. `scopeQuery` is passed pre-
+ * serialized by the caller (a plain object is not itself hashable
+ * material) so this function stays a thin, generic hasher rather than
+ * embedding export-briefing.js's own scopeQuery shape.
+ */
+export function storyId(
+  { graphDigest, audienceMode, scopeQuery },
+  discriminatorParts = [],
+) {
+  const scope = typeof scopeQuery === 'string' ? scopeQuery : JSON.stringify(scopeQuery ?? null);
+  return `story:${_hash(_canon([graphDigest, audienceMode, scope, ...discriminatorParts]))}`;
+}
+
+/**
+ * A GraphSnapshot record's id (M4 deliverable #8, FR-503 §14, DFG-022,
+ * sub-project 8a) — NOT a DataFlowGraph v1 entity, mirrors obligationId's/
+ * storyId's own precedent exactly (a real, stable-ID'd extension record
+ * that is deliberately not a base-graph entity). Discriminated by
+ * (graphId, commit, capturedAt) — `commit` is the REAL git HEAD resolved
+ * by graph-snapshot.js's own persistence layer, never `graphId`'s own
+ * embedded commit component (which is the literal string 'uncommitted' on
+ * every real scan today — see graph-snapshot.js's own header comment).
+ */
+export function snapshotId(
+  { graphId, commit, capturedAt },
+  discriminatorParts = [],
+) {
+  return `snapshot:${_hash(_canon([graphId, commit, capturedAt, ...discriminatorParts]))}`;
+}
+
+/**
+ * A GraphDiff record's id (M4 deliverable #9, FR-503 §14, DFG-022,
+ * sub-project 8b) — NOT a DataFlowGraph v1 entity, mirrors snapshotId's
+ * own precedent exactly (a real, stable-ID'd extension record that is
+ * deliberately not a base-graph entity). Discriminated by
+ * (beforeSnapshotId, afterSnapshotId) — unlike snapshotId, no separate
+ * timestamp component is needed: each snapshot id is itself
+ * content-derived (its own graphId/commit/capturedAt), so the pair alone
+ * already makes a diff between two SPECIFIC snapshots deterministic, and
+ * a diff is not itself a new capture event the way a snapshot is.
+ */
+export function diffId(
+  { beforeSnapshotId, afterSnapshotId },
+  discriminatorParts = [],
+) {
+  return `diff:${_hash(_canon([beforeSnapshotId, afterSnapshotId, ...discriminatorParts]))}`;
+}
+
+/**
+ * A Scenario record's id (M5 deliverable #3a, FR-502 §10.10) — NOT a
+ * DataFlowGraph v1 entity, mirrors recipientProfileId's own precedent
+ * exactly (a real, stable-ID'd extension record deliberately not a
+ * base-graph entity). Discriminated by (graphId, graphDigest) plus
+ * caller-supplied discriminatorParts — unlike recipientProfileId, a
+ * Scenario has no single natural key of its own (two saved scenarios
+ * over the identical base graph with identical operations are still
+ * two different records, since FR-502 requires author/time as real,
+ * always-present, non-deduplicating fields), so a caller building a
+ * scenario record supplies (author, createdAt) as discriminatorParts to
+ * make repeat calls collide only when they are genuinely the same
+ * scenario.
+ */
+export function scenarioId(
+  { graphId, graphDigest },
+  discriminatorParts = [],
+) {
+  return `scenario:${_hash(_canon([graphId, graphDigest, ...discriminatorParts]))}`;
+}
+
+/**
+ * An ImpactAssessment record's id (M5 deliverable #4, FR-507 §10.10) —
+ * NOT a DataFlowGraph v1 entity, mirrors recipientProfileId's/
+ * scenarioId's own precedent exactly. Discriminated by (graphId,
+ * graphDigest, targetId) plus caller-supplied discriminatorParts —
+ * graphDigest is required for the identical reason every other
+ * extension-contract id in this file requires it (graphId alone never
+ * distinguishes two same-commit graphs with genuinely different
+ * content); targetId is the compromised entity the assessment was
+ * computed FROM, so two assessments over the same graph but different
+ * targets never collide. Mirrors scenarioId's own (author, createdAt)
+ * precedent for discriminatorParts: the only real caller
+ * (impact-engine.js) always supplies `[generatedAt]`, so two
+ * back-to-back assessments of the SAME target over an UNCHANGED graph
+ * get distinct ids per run (a content-addressed id that collided
+ * across runs would be strictly worse than a per-run one — graphDigest
+ * already covers "the graph changed", generatedAt is purely a per-run
+ * nonce, the same role snapshotId's own capturedAt plays).
+ */
+export function impactAssessmentId(
+  { graphId, graphDigest, targetId },
+  discriminatorParts = [],
+) {
+  return `impact:${_hash(_canon([graphId, graphDigest, targetId, ...discriminatorParts]))}`;
+}
+
+/**
+ * A RuntimeObservation record's id (M5 deliverable #7, FR-505 §10.10) —
+ * NOT a DataFlowGraph v1 entity, mirrors impactAssessmentId's/scenarioId's
+ * own precedent exactly. Discriminated by (adapter, environment,
+ * windowStart, windowEnd) plus caller-supplied discriminatorParts, which
+ * the adapter fills with the observation's own attribute fingerprint —
+ * two observations of the SAME destination in the SAME environment and
+ * window are the same observation and must collapse to one id, which is
+ * what makes an accidental double-import idempotent at the record level.
+ */
+export function observationId(
+  { adapter, environment, windowStart, windowEnd },
+  discriminatorParts = [],
+) {
+  return `observation:${_hash(_canon([adapter, environment, windowStart, windowEnd, ...discriminatorParts]))}`;
+}
+
+/**
+ * One adapter IMPORT's id (M5 deliverable #7, FR-505 §10.10) — the store's
+ * own file key, mirroring graph-snapshot.js's commit key one dimension
+ * over (import, not commit; see that sub-project's scoping doc §4.4 for
+ * why commit-keying cannot express many observations per graph entity).
+ * `importedAt` is a per-run nonce, exactly the role snapshotId's own
+ * capturedAt plays: re-importing the same file must produce a NEW import
+ * file, never silently overwrite the earlier one, because the store is a
+ * directory of IMMUTABLE whole files.
+ */
+export function observationImportId(
+  { adapter, source, environment, windowStart, windowEnd, importedAt },
+  discriminatorParts = [],
+) {
+  return `obsimport:${_hash(_canon([adapter, source, environment, windowStart, windowEnd, importedAt, ...discriminatorParts]))}`;
+}
+
+/**
+ * A CrossRepoLink record's id (M5 deliverable #8, FR-304 "declared"
+ * half, §10.10) — NOT a DataFlowGraph v1 entity, mirrors
+ * `recipientProfileId`'s own precedent exactly: `(graphId, graphDigest,
+ * ...)` doubled for both endpoints. This is the concrete mechanism that
+ * makes "id collision is impossible by construction" real rather than
+ * aspirational: two links between structurally identical node shapes in
+ * two different repo pairs cannot collide, because both graphs' own
+ * `graphId`+`graphDigest` are baked into the id material on both sides —
+ * a bare node id string is never looked up against a merged or ambiguous
+ * set.
+ */
+export function crossRepoLinkId(
+  {
+    localGraphId, localGraphDigest, localNodeId,
+    remoteGraphId, remoteGraphDigest, remoteNodeId,
+    relationship,
+  },
+  discriminatorParts = [],
+) {
+  return `crosslink:${_hash(_canon([
+    localGraphId, localGraphDigest, localNodeId,
+    remoteGraphId, remoteGraphDigest, remoteNodeId,
+    relationship, ...discriminatorParts,
+  ]))}`;
+}

package/src/lineage/impact-assessment.js

@@ -0,0 +1,76 @@
+// impact-assessment.js — M5 deliverable #4 (FR-507 §10.10): the
+// ImpactAssessment extension contract — the result of asking "what is
+// reachable from this compromised node/edge/flow/data element, per the
+// graph's own already-scanned evidence." NOT a DataFlowGraph v1 entity,
+// mirrors recipient-profile.js's/scenario.js's own contract shape
+// exactly (structural-only {valid, errors} validator, zero graph
+// access at construction time).
+//
+// See docs/superpowers/plans/2026-09-02-data-flow-explorer-m5-blast-radius-impact-scoping.md
+// for the full design reasoning, including why there is no
+// affectedObligationIds field (ObligationMapping records are built on
+// demand per compliance framework, not stored on the graph) and why
+// `scope` is always 'possible' today (no runtime-corroboration layer
+// exists yet).
+
+export const IMPACT_VERSION = '1.0.0';
+
+export const IMPACT_TARGET_KINDS = Object.freeze(['node', 'edge', 'flow', 'dataElement']);
+
+// 'possible' is the only value any producer emits today — 'observed'
+// is reserved for a future Digital Twin (M5 #7) increment with a real
+// runtime-corroboration signal. Both are valid schema values now so
+// that increment needs no breaking change to this contract later.
+export const IMPACT_SCOPE_VALUES = Object.freeze(['possible', 'observed']);
+
+// Discloses WHICH of the two genuinely different traversal semantics
+// produced this record (final-review I2 fix) — `scope` alone cannot
+// distinguish them, since both families emit `scope: 'possible'`.
+// 'topology_reachable': a `node` target's topology-wide showAllPaths
+// BFS — "everything this compromised node could push to." 'flow_
+// restricted': an `edge`/`flow`/`dataElement` target's direct trace
+// over the flows that actually carry it — never the topology-wide BFS.
+// Without this field a JSON consumer cannot tell "exact carrier trace"
+// from "topological presumption" apart, the exact silent-conflation
+// this codebase's own disclosure discipline exists to prevent.
+export const IMPACT_TRACE_KINDS = Object.freeze(['topology_reachable', 'flow_restricted']);
+
+function _isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
+function _isStringArray(v) { return Array.isArray(v) && v.every((x) => typeof x === 'string'); }
+
+/**
+ * Structural validation only — mirrors validateRecipientProfile's/
+ * validateScenario's own {valid, errors} shape and "never throws"
+ * contract.
+ */
+export function validateImpactAssessment(record) {
+  const errors = [];
+  const err = (p, message) => errors.push({ path: p, message });
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    err('$', 'ImpactAssessment record must be an object');
+    return { valid: false, errors };
+  }
+  if (!_isNonEmptyString(record.id) || !record.id.startsWith('impact:')) {
+    err('$.id', 'id is required and must start with "impact:"');
+  }
+  if (!_isNonEmptyString(record.version)) err('$.version', 'version is required');
+  if (!_isNonEmptyString(record.graphId)) err('$.graphId', 'graphId is required');
+  if (!_isNonEmptyString(record.graphDigest)) err('$.graphDigest', 'graphDigest is required');
+  if (!_isNonEmptyString(record.targetId)) err('$.targetId', 'targetId is required');
+  if (!IMPACT_TARGET_KINDS.includes(record.targetKind)) {
+    err('$.targetKind', `targetKind must be one of ${IMPACT_TARGET_KINDS.join('|')}`);
+  }
+  if (!IMPACT_SCOPE_VALUES.includes(record.scope)) {
+    err('$.scope', `scope must be one of ${IMPACT_SCOPE_VALUES.join('|')}`);
+  }
+  if (!IMPACT_TRACE_KINDS.includes(record.traceKind)) {
+    err('$.traceKind', `traceKind must be one of ${IMPACT_TRACE_KINDS.join('|')}`);
+  }
+  if (!_isStringArray(record.affectedNodeIds ?? [])) err('$.affectedNodeIds', 'affectedNodeIds must be an array of strings');
+  if (!_isStringArray(record.affectedEdgeIds ?? [])) err('$.affectedEdgeIds', 'affectedEdgeIds must be an array of strings');
+  if (!_isStringArray(record.affectedDataClasses ?? [])) err('$.affectedDataClasses', 'affectedDataClasses must be an array of strings');
+  if (!_isStringArray(record.affectedRecipientProfileIds ?? [])) err('$.affectedRecipientProfileIds', 'affectedRecipientProfileIds must be an array of strings');
+  if (!_isStringArray(record.coverageLimitations ?? [])) err('$.coverageLimitations', 'coverageLimitations must be an array of strings');
+  if (!_isNonEmptyString(record.generatedAt)) err('$.generatedAt', 'generatedAt is required');
+  return { valid: errors.length === 0, errors };
+}