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

package/src/lineage/scenario-engine.js

@@ -0,0 +1,251 @@
+// scenario-engine.js — M5 deliverable #3a (FR-502): the clone-and-
+// override engine. Deep-clones the base graph, applies each declared
+// Scenario operation, then re-runs the SAME two pure aggregators
+// graph-builder.js's own real pipeline uses (aggregateVerdicts,
+// isSinkPermitted) over only the flows an operation actually touched —
+// never re-running the taint/path pipeline, per this sub-project's own
+// scoping doc.
+//
+// The exact recomputation this module mirrors, confirmed by direct
+// read of graph-builder.js's own real edge/flow minting pass:
+//   flow.protectionSummary = aggregateVerdicts([
+//     edge.protection.transit.verdict,
+//     edge.protection.atRest.verdict,
+//     edge.protection.handling.verdict,
+//   ])
+//   flow.policyVerdict = isSinkPermitted(dataElement.dataClasses, sinkNode.subtype,
+//     opts.privacySinkPolicy, { environment: opts.environment, destination: sinkNode.destination?.literalValue ?? null })
+//     ? 'permitted' : 'prohibited'  (or 'not_evaluated' if no policy/classes/sinkKind)
+
+import { aggregateVerdicts } from './protection.js';
+import { isSinkPermitted } from '../dataflow/privacy-sink-policy.js';
+
+function _deepClone(v) { return JSON.parse(JSON.stringify(v)); }
+
+function _byId(arr) { return new Map((arr ?? []).map((x) => [x.id, x])); }
+
+// Aggregates protectionSummary across EVERY edge belonging to `flow`, not
+// just one of them — a flow's `edgeIds` can in principle name more than
+// one edge (graph-builder.js's own real flows are always single-edge
+// today, but the schema and this module both accept a multi-edge array
+// with no restriction), and aggregateVerdicts's own documented purpose is
+// exactly this cross-branch/cross-edge reduction (PRD §8.4). Picking a
+// single arbitrary edge here would silently go stale the moment a
+// scenario is built against a genuinely multi-hop flow.
+function _recomputeProtectionSummaryForFlow(flow, graph) {
+  const edges = graph.edges.filter((e) => flow.edgeIds.includes(e.id));
+  const verdicts = edges.flatMap((e) => [
+    e.protection.transit.verdict,
+    e.protection.atRest.verdict,
+    e.protection.handling.verdict,
+  ]);
+  return aggregateVerdicts(verdicts);
+}
+
+function _recomputePolicyVerdict(flow, graph, opts) {
+  if (opts.privacySinkPolicy == null) return null; // signal: leave flow.policyVerdict untouched
+  const de = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+  const sinkNode = graph.nodes.find((n) => n.id === flow.sink);
+  const classes = de?.dataClasses ?? [];
+  const sinkKind = sinkNode?.subtype ?? null;
+  if (!classes.length || !sinkKind) return 'not_evaluated';
+  const ctx = {
+    environment: opts.environment ?? process.env.AGENTIC_SECURITY_ENVIRONMENT ?? null,
+    destination: sinkNode?.destination?.literalValue ?? null,
+  };
+  return isSinkPermitted(classes, sinkKind, opts.privacySinkPolicy, ctx) ? 'permitted' : 'prohibited';
+}
+
+// Every flow using this edge (by edgeIds membership) gets protectionSummary
+// recomputed; policyVerdict only for flows whose sink node's destination
+// or the flow's own dataClasses could plausibly have changed — but since
+// applyScenario always calls this after ANY node/edge touch to be safe
+// (recomputation is cheap and idempotent), scope is simply "every flow
+// touching this edge or this node".
+function _touchedFlows(graph, { edgeId, nodeId }) {
+  return graph.flows.filter((f) =>
+    (edgeId && f.edgeIds.includes(edgeId)) ||
+    (nodeId && (f.source === nodeId || f.sink === nodeId)));
+}
+
+function _recomputeTouchedFlows(graph, touch, opts) {
+  for (const flow of _touchedFlows(graph, touch)) {
+    flow.protectionSummary = _recomputeProtectionSummaryForFlow(flow, graph);
+    const newPolicyVerdict = _recomputePolicyVerdict(flow, graph, opts);
+    if (newPolicyVerdict !== null) flow.policyVerdict = newPolicyVerdict;
+  }
+}
+
+function _applyRequireTransitProtection(graph, op) {
+  const edge = _byId(graph.edges).get(op.targetEdgeId);
+  if (!edge) return { ok: false, reason: `targetEdgeId "${op.targetEdgeId}" not found in graph.edges` };
+  edge.protection.transit = { verdict: 'protected', evidenceGrade: 'assumed' };
+  _recomputeTouchedFlows(graph, { edgeId: edge.id }, op._opts);
+  return { ok: true };
+}
+
+function _applyHandling(graph, op) {
+  const edge = _byId(graph.edges).get(op.targetEdgeId);
+  if (!edge) return { ok: false, reason: `targetEdgeId "${op.targetEdgeId}" not found in graph.edges` };
+  // Mirrors graph-builder.js's own gate (~line 757): 'encrypted' handling
+  // only earns the atRest 'protected' verdict when the edge's sink node
+  // is store-kind (database/file/object-storage/cache/client-storage/
+  // backup/export). For any other sink kind (e.g. 'external-api',
+  // 'queue') "at rest" isn't even a meaningful concept — falls through to
+  // the same 'handling' dimension the non-encrypted case already sets.
+  const sinkNode = graph.nodes.find((n) => n.id === edge.to);
+  if (op.handling === 'encrypted' && sinkNode?.kind === 'store') {
+    edge.protection.atRest = { verdict: 'protected', evidenceGrade: 'assumed' };
+  } else {
+    edge.protection.handling = { verdict: 'protected', evidenceGrade: 'assumed' };
+  }
+  _recomputeTouchedFlows(graph, { edgeId: edge.id }, op._opts);
+  return { ok: true };
+}
+
+function _applyRemoveEntity(graph, op) {
+  const node = _byId(graph.nodes).get(op.targetNodeId);
+  if (!node) return { ok: false, reason: `targetNodeId "${op.targetNodeId}" not found in graph.nodes` };
+  const removedEdgeIds = new Set(graph.edges.filter((e) => e.from === node.id || e.to === node.id).map((e) => e.id));
+  graph.edges = graph.edges.filter((e) => !removedEdgeIds.has(e.id));
+  graph.flows = graph.flows.filter((f) => f.source !== node.id && f.sink !== node.id
+    && !f.edgeIds.some((id) => removedEdgeIds.has(id)));
+  graph.nodes = graph.nodes.filter((n) => n.id !== node.id);
+  // Cascade-prune graph.recipientProfiles[] too — a RecipientProfile whose
+  // contributingGraphIds referenced ONLY this now-removed node must not
+  // survive dangling (a downstream `dataflow export --format recipients`
+  // consumer filters by exactly contributingGraphIds against surviving
+  // node ids); a profile with OTHER surviving contributing ids just loses
+  // this one id, never the whole record. Guarded on the array existing —
+  // the base graph shape used throughout this sub-project's own tests
+  // doesn't always include it. A profile with NO contributingGraphIds at
+  // all (null/undefined — real graph-builder.js output always mints a
+  // non-empty array, so this is defensive against a hand-built/external
+  // graph only) is left untouched rather than normalized to `[]` and
+  // dropped, since a missing array is not evidence the profile referenced
+  // this node.
+  // NOTE (final-review re-review N2, disclosed not fixed): this cascade
+  // is real graph mutation, but scenario-diff.js's WATCHED_SCENARIO_FIELDS
+  // has no `recipientProfile` kind, so diffScenarioGraph's own delta
+  // report stays silent about a recipient record that disappeared or lost
+  // a contributing id here — a future increment's fuller fix, not scope
+  // creep for this pass.
+  if (graph.recipientProfiles?.length) {
+    graph.recipientProfiles = graph.recipientProfiles
+      .map((rp) => (rp.contributingGraphIds == null ? rp
+        : { ...rp, contributingGraphIds: rp.contributingGraphIds.filter((id) => id !== node.id) }))
+      .filter((rp) => rp.contributingGraphIds == null || rp.contributingGraphIds.length > 0);
+  }
+  return { ok: true };
+}
+
+// Scoped, at the applier level, to exactly `node.destination` — this
+// sub-project's own scoping doc maps "replace a provider or move region"
+// onto node.destination, the graph-level equivalent of a recipient's
+// technical endpoint, and nothing else. scenario.js's own
+// SCENARIO_OPERATION_REQUIRED_FIELDS only requires `field` be a non-empty
+// string, never restricts its value — a real applied write to any other
+// top-level node field (e.g. 'subtype') would land on the node but be
+// completely invisible to scenario-diff.js's WATCHED_SCENARIO_FIELDS.node
+// (which only watches 'destination'/'storeDetail'), since that list can
+// only stay exhaustive if this applier never writes outside it. Rejecting
+// any other field here — never widening the watch list — is what keeps
+// that list exhaustive by construction. Mirrors the existing "skip a
+// target id it can't find" pattern: reported in skippedOperations, never
+// thrown.
+function _applyReplaceRecipientFact(graph, op) {
+  const node = _byId(graph.nodes).get(op.targetNodeId);
+  if (!node) return { ok: false, reason: `targetNodeId "${op.targetNodeId}" not found in graph.nodes` };
+  if (op.field !== 'destination') {
+    return { ok: false, reason: `replace_recipient_fact only supports field "destination" (got "${op.field}") — this operation is scoped to a node's recipient/destination fact only` };
+  }
+  node[op.field] = _deepClone(op.value);
+  // The destination just changed — any edge.protection.transit verdict INTO
+  // this node was derived from the OLD destination (transit-protection.js's
+  // resolveTransitProtectionForSite is keyed on the sink's own destination)
+  // and is now stale. Never let a stale verdict survive with a real (non-
+  // 'assumed') evidence grade — reset to the honest "we don't know anymore"
+  // state rather than re-derive (re-deriving needs transitEvidenceByFile,
+  // IR-level data unavailable post-build) or silently keep the old verdict.
+  // NOTE (final-review re-review N1, disclosed not fixed): this demotion is
+  // per-EDGE and is always honest at that level (and always visible in
+  // diffScenarioGraph's own delta, since edge.protection.transit is a
+  // WATCHED_SCENARIO_FIELDS.edge entry) — but flow.protectionSummary
+  // aggregates transit/atRest/handling via aggregateVerdicts, whose
+  // precedence ranks not_assessed LAST, so a scenario that ALSO sets this
+  // edge's own handling dimension to 'protected' (via apply_handling) in
+  // the SAME operations list can mask the demotion at the flow-summary
+  // level, even though the masking verdict itself is honestly graded
+  // 'assumed'. graph-builder.js's own cross-dimension aggregation is
+  // documented safe only because transit/atRest are mutually exclusive by
+  // construction and handling is "never written" by any real analyzer —
+  // this module (scenario-engine.js) is the one exception to that last
+  // clause, which is exactly what makes the masking reachable here.
+  for (const edge of graph.edges) {
+    if (edge.to === node.id) {
+      edge.protection.transit = { verdict: 'not_assessed', evidenceGrade: 'none' };
+    }
+  }
+  _recomputeTouchedFlows(graph, { nodeId: node.id }, op._opts);
+  return { ok: true };
+}
+
+function _applyChangeStorageFact(graph, op) {
+  const node = _byId(graph.nodes).get(op.targetNodeId);
+  if (!node) return { ok: false, reason: `targetNodeId "${op.targetNodeId}" not found in graph.nodes` };
+  node.storeDetail = { ...(node.storeDetail ?? {}), [op.field]: _deepClone(op.value) };
+  return { ok: true };
+}
+
+function _applyChangeGovernanceFact(graph, op) {
+  const flow = _byId(graph.flows).get(op.targetFlowId);
+  if (!flow) return { ok: false, reason: `targetFlowId "${op.targetFlowId}" not found in graph.flows` };
+  flow.governanceRefs = { ...(flow.governanceRefs ?? {}), [op.field]: _deepClone(op.value) };
+  return { ok: true };
+}
+
+const _APPLIERS = {
+  require_transit_protection: _applyRequireTransitProtection,
+  apply_handling: _applyHandling,
+  remove_entity: _applyRemoveEntity,
+  replace_recipient_fact: _applyReplaceRecipientFact,
+  change_storage_fact: _applyChangeStorageFact,
+  change_governance_fact: _applyChangeGovernanceFact,
+};
+
+/**
+ * Apply `scenario.operations` to a deep clone of `baseGraph`. Never
+ * mutates `baseGraph`. An operation whose target id does not exist in
+ * the graph is skipped (reported in `skippedOperations`), never thrown —
+ * a Scenario written against an older snapshot must degrade honestly.
+ * `opts.privacySinkPolicy`/`opts.environment` mirror graph-builder.js's
+ * own opts; omitting privacySinkPolicy means policyVerdict
+ * recomputation is skipped entirely (base value kept on every touched
+ * flow) rather than guessed.
+ *
+ * Scenario-shape validation (`validateScenario`, `scenario.js`) is the
+ * CALLER's responsibility, not this module's — this function does no
+ * upfront shape checking beyond each operation's own per-target `_byId`
+ * lookup. An unrecognized `op.kind` is skipped via the `_APPLIERS` map
+ * lookup below rather than validated against `SCENARIO_OPERATION_KINDS`
+ * ahead of time. This mirrors `recipient-profile.js`'s own precedent,
+ * where `validateRecipientProfile` is never called internally by any
+ * producer either — the CLI layer (Task 4) calls `validateScenario`
+ * before `applyScenario`, by design.
+ */
+export function applyScenario(baseGraph, scenario, opts = {}) {
+  const graph = _deepClone(baseGraph);
+  const appliedOperations = [];
+  const skippedOperations = [];
+  for (const op of scenario.operations ?? []) {
+    const applier = _APPLIERS[op.kind];
+    if (!applier) {
+      skippedOperations.push({ operation: op, reason: `unrecognized operation kind "${op.kind}"` });
+      continue;
+    }
+    const result = applier(graph, { ...op, _opts: opts });
+    if (result.ok) appliedOperations.push({ operation: op });
+    else skippedOperations.push({ operation: op, reason: result.reason });
+  }
+  return { graph, appliedOperations, skippedOperations };
+}

package/src/lineage/scenario.js

@@ -0,0 +1,101 @@
+// scenario.js — M5 deliverable #3a (FR-502 §10.10, DFG-0xx): the
+// Scenario extension contract — a hypothetical set of graph overrides,
+// NOT a DataFlowGraph v1 entity, mirrors recipient-profile.js's own
+// contract shape exactly (structural-only {valid, errors} validator,
+// zero graph access, per-field evidence typing for the fields a
+// Scenario actually overrides).
+//
+// See docs/superpowers/plans/2026-09-02-data-flow-explorer-m5-whatif-simulator-scoping.md
+// for the full design reasoning, including why EVIDENCE_GRADES gained
+// 'assumed' instead of reusing 'declared', and why this module's own
+// operations catalog excludes synthetic node/edge insertion (deferred).
+
+export const SCENARIO_VERSION = '1.0.0';
+
+// The 6 in-scope hypothetical-change kinds (FR-502's own 7, minus the
+// deferred synthetic-insertion category). Each operation names its
+// target canonical id(s) plus the override value(s); scenario-engine.js
+// is the only consumer that interprets `kind`.
+export const SCENARIO_OPERATION_KINDS = Object.freeze([
+  'require_transit_protection',
+  'apply_handling',
+  'remove_entity',
+  'replace_recipient_fact',
+  'change_storage_fact',
+  'change_governance_fact',
+]);
+
+// Per-operation-kind required fields, beyond the universal `kind`. Kept
+// as data (not inline in validateScenario) for the same reason
+// SCENARIO_OPERATION_KINDS above is — a single source of truth a table
+// can be checked against — though scenario-engine.js does not currently
+// import this table itself; it only mentions it in a prose comment on
+// its own _applyReplaceRecipientFact.
+export const SCENARIO_OPERATION_REQUIRED_FIELDS = Object.freeze({
+  require_transit_protection: ['targetEdgeId'],
+  apply_handling: ['targetEdgeId', 'handling'],
+  remove_entity: ['targetNodeId'],
+  replace_recipient_fact: ['targetNodeId', 'field', 'value'],
+  change_storage_fact: ['targetNodeId', 'field', 'value'],
+  change_governance_fact: ['targetFlowId', 'field', 'value'],
+});
+
+function _isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
+function _isPlainObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+function _isStringArray(v) { return Array.isArray(v) && v.every((x) => typeof x === 'string'); }
+
+/**
+ * Structural validation only — mirrors validateRecipientProfile's own
+ * {valid, errors} shape and "never throws" contract. Does not check
+ * that targetEdgeId/targetNodeId/targetFlowId actually exist in any
+ * real graph — that is scenario-engine.js's job at apply time, since
+ * this module has zero graph access by design.
+ */
+export function validateScenario(record) {
+  const errors = [];
+  const err = (p, message) => errors.push({ path: p, message });
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    err('$', 'Scenario record must be an object');
+    return { valid: false, errors };
+  }
+  if (!_isNonEmptyString(record.id) || !record.id.startsWith('scenario:')) {
+    err('$.id', 'id is required and must start with "scenario:"');
+  }
+  if (!_isNonEmptyString(record.version)) err('$.version', 'version is required');
+  if (!_isNonEmptyString(record.baseGraphId)) err('$.baseGraphId', 'baseGraphId is required');
+  if (!_isNonEmptyString(record.baseGraphDigest)) err('$.baseGraphDigest', 'baseGraphDigest is required');
+  if (!_isNonEmptyString(record.author)) err('$.author', 'author is required');
+  if (!_isNonEmptyString(record.createdAt)) err('$.createdAt', 'createdAt is required');
+  if (record.expiration !== null && record.expiration !== undefined && !_isNonEmptyString(record.expiration)) {
+    err('$.expiration', 'expiration must be a string or null');
+  }
+  if (!_isStringArray(record.assumptions ?? [])) err('$.assumptions', 'assumptions must be an array of strings');
+  if (!_isStringArray(record.verificationRequirements ?? [])) {
+    err('$.verificationRequirements', 'verificationRequirements must be an array of strings');
+  }
+  if (!Array.isArray(record.operations) || record.operations.length === 0) {
+    err('$.operations', 'operations is required and must be a non-empty array');
+  } else {
+    record.operations.forEach((op, i) => {
+      const p = `$.operations[${i}]`;
+      if (!_isPlainObject(op)) { err(p, 'each operation must be an object'); return; }
+      if (!SCENARIO_OPERATION_KINDS.includes(op.kind)) {
+        err(`${p}.kind`, `unrecognized operation kind "${op.kind}" — must be one of ${SCENARIO_OPERATION_KINDS.join('|')}`);
+        return;
+      }
+      for (const field of SCENARIO_OPERATION_REQUIRED_FIELDS[op.kind]) {
+        if (op[field] === undefined || op[field] === null || op[field] === '') {
+          err(`${p}.${field}`, `operation of kind "${op.kind}" requires "${field}"`);
+        }
+      }
+    });
+  }
+  // simulatedDelta is populated by scenario-engine.js after apply, never
+  // by a caller constructing the pre-apply record — null is the only
+  // valid pre-apply value, an object (scenario-diff.js's own shape) the
+  // only valid post-apply value.
+  if (record.simulatedDelta !== null && record.simulatedDelta !== undefined && !_isPlainObject(record.simulatedDelta)) {
+    err('$.simulatedDelta', 'simulatedDelta must be null (before apply) or an object (after apply)');
+  }
+  return { valid: errors.length === 0, errors };
+}

package/src/lineage/schema.js

@@ -0,0 +1,167 @@
+//
+// DataFlowGraph v1 — canonical envelope and enum contract (Data Flow
+// Explorer PRD section 10). This module carries only pure constants and
+// the empty-envelope constructor; no analysis logic lives here. A change
+// to any array below is a schema-version-bumping change.
+//
+// Isolated from scanner/src/dataflow/ on purpose (PRD section 18.1): this
+// package may read pure, stateless exports from dataflow/privacy-taxonomy.js
+// but must never import scanner/src/dataflow/engine.js or touch its taint
+// state.
+
+export const SCHEMA_VERSION = '1.0.0';
+
+export const NODE_KINDS = Object.freeze([
+  'source', 'process', 'transform', 'api', 'store', 'queue',
+  'log', 'sink', 'external', 'boundary', 'unresolved',
+]);
+
+export const MAPPING_TYPES = Object.freeze([
+  'identity', 'rename', 'projection', 'serialization', 'deserialization',
+  'transformation', 'aggregation', 'join', 'filter', 'sort', 'conditional', 'unknown',
+]);
+
+export const TRANSFORM_KINDS = Object.freeze([
+  'mask', 'redact', 'tokenize', 'hash', 'encrypt', 'decrypt', 'encode',
+  'decode', 'aggregate', 'truncate', 'normalize', 'custom', 'unknown',
+]);
+
+export const REVERSIBILITY_VALUES = Object.freeze(['reversible', 'irreversible', 'unknown']);
+
+// FR-403's single-path handling TAXONOMY (Milestone 2, Sub-project D,
+// increment 1 — DESIGN_HANDLING_ANALYZER.md). Lives on `flow.handling`, a
+// STRING enum — deliberately NOT the same thing as `protection.js`'s
+// `PROTECTION_DIMENSIONS`' own `handling` dimension (an per-EDGE
+// `{verdict, evidenceGrade}` object scored from `PROTECTION_VERDICTS`).
+// The two share a name because this taxonomy IS what a later Milestone 2
+// analyzer will read to populate that verdict (transform-catalog.js's own
+// header: "Recognizing that a `mask` happened is this module's job.
+// Deciding whether that `mask` earns 'protected' is Milestone 2's FR-401-
+// 405 analyzers, reading this module's output.") — but the two fields are
+// never the same value, never interchangeable, and this increment sets
+// only `flow.handling`, never `edge.protection.handling`.
+export const HANDLING_VALUES = Object.freeze([
+  'raw', 'masked', 'redacted', 'hashed', 'tokenized', 'encrypted', 'aggregated', 'unknown',
+]);
+
+export const EXTERNALITY_VALUES = Object.freeze(['internal', 'external', 'unknown']);
+
+export const COVERAGE_STATUS_VALUES = Object.freeze(['modeled', 'partial', 'candidate', 'unsupported', 'manual']);
+
+// Milestone 5, language coverage-tier disclosure: a product-level tier for
+// an entire LANGUAGE (per docs/METRICS.md's own curated recall measurements),
+// deliberately NOT a reuse of COVERAGE_STATUS_VALUES above — that enum
+// answers a different question (is this one NODE's own classification
+// confident), not "does this language, as a whole, clear the PRD's own
+// field-to-sink recall bar." 'full' is real and reachable (a future
+// docs/METRICS.md update crossing 85% needs no code change here to report
+// it) even though no language currently resolves to it.
+export const LANGUAGE_COVERAGE_TIER_VALUES = Object.freeze(['full', 'partial', 'pattern-only', 'unknown']);
+
+export const DESTINATION_RESOLUTION_VALUES = Object.freeze([
+  'literal', 'resolved_from_constant', 'resolved_from_config', 'resolved_from_schema',
+  'declared_service', 'runtime_corroborated', 'dynamic', 'unknown',
+]);
+
+// Milestone 2, Sub-project F, increment 1 (FR-304): which mechanism
+// discovered this edge. Deliberately value-aligned with (but a
+// distinct field from) EVIDENCE_TYPES — 'code'/'schema'/'manual'/
+// 'runtime' are FR-304's own four categories, reusing EVIDENCE_TYPES's
+// existing spellings rather than inventing a second vocabulary for the
+// same four concepts. Only 'code' has a real producer today
+// (graph-builder.js sets it unconditionally); 'schema'/'manual'/
+// 'runtime' are reserved for Sub-project F2/F3, not yet implemented —
+// see scanner/src/lineage/CLAUDE.md.
+export const EDGE_PROVENANCE_VALUES = Object.freeze(['code', 'schema', 'manual', 'runtime']);
+
+// Milestone 2, Sub-project E, increment 2 (`node.storeDetail.operation`,
+// DESIGN_STORE_DETAIL.md). `save` deliberately maps to `'upsert'`, never
+// `'create'` — see graph-builder.js's own method-name mapping comment for
+// the full reasoning (Mongoose's `.save()` is an INSERT on a new document
+// but an UPDATE on one loaded from the database, genuinely undecidable
+// statically from the call site alone; `'upsert'` is the honest umbrella,
+// not a guess at which one).
+export const STORE_OPERATION_VALUES = Object.freeze(['create', 'read', 'update', 'delete', 'upsert', 'unknown']);
+
+// Milestone 2, Sub-project E, increment 3 (`node.queueDetail.operation`,
+// DESIGN_QUEUE_DETAIL.md). Only two values, deliberately — both real
+// PRIVACY_SINK_CATALOG queue entries (`sendMessage`, `publish`) are
+// unambiguously a WRITE/publish operation, unlike the database case's real
+// `create`/`update`/`upsert` spread; there is no `read`/`delete`/`create`
+// ambiguity to disclose here. Every queue site this increment recognizes
+// gets `operation: 'publish'` — never `'unknown'` in practice today (no
+// catalog entry produces anything else), but the value exists so
+// `validate.js`'s structural check has a real enum to check against, the
+// same "define the vocabulary even if only one value is reachable today"
+// precedent `HANDLING_VALUES`/`STORE_OPERATION_VALUES` both already
+// established.
+export const QUEUE_OPERATION_VALUES = Object.freeze(['publish', 'unknown']);
+
+export const POLICY_STATES = Object.freeze([
+  'prohibited', 'permitted', 'conditionally_permitted', 'manual_review_required', 'not_evaluated',
+]);
+
+export const EVIDENCE_TYPES = Object.freeze([
+  'code', 'ir', 'configuration', 'iac', 'schema', 'service_declaration', 'policy', 'manual', 'runtime',
+]);
+
+export const FLOW_SUMMARY_VALUES = Object.freeze(['protected', 'unprotected', 'mixed', 'unknown', 'not_assessed']);
+
+// Not named in the PRD's own envelope example (section 10.2) but required
+// by Appendix D.1's "no special-casing by name" rule: the UI needs a
+// GENERIC signal for the "Illustrative demo data" ribbon, not a check
+// against a specific fixture filename or node id.
+export const GRAPH_SCOPE_SOURCES = Object.freeze(['scan', 'fixture']);
+
+// PRD section 11 (FR-101) source categories and section 12 (FR-201) sink
+// categories — the fixed vocabulary a node's `subtype`/an inventory row's
+// category field draws from. This is the TAXONOMY only; the pattern-
+// matching registries that recognize one of these categories in real
+// source code (source-registry.js / sink-registry.js, PRD DFG-003) are
+// Milestone 1, not this module.
+export const SOURCE_CATEGORIES = Object.freeze([
+  'http-body', 'http-query', 'http-route', 'http-header', 'http-cookie', 'http-upload',
+  'graphql-argument', 'grpc-field', 'cli-argument', 'env-value', 'queue-message',
+  'database-read', 'storage-read', 'user-input', 'external-api-response',
+  'webhook-payload', 'ai-model-output', 'ai-tool-result', 'ai-retrieved-document',
+  'ai-memory', 'declared',
+]);
+
+export const SINK_CATEGORIES = Object.freeze([
+  'log', 'stdout', 'http-response', 'client-storage', 'database', 'file', 'object-storage',
+  'cache', 'queue', 'analytics', 'monitoring', 'email', 'sms', 'push-notification', 'collaboration',
+  'external-api', 'webhook', 'ai-model-provider', 'ai-local-model', 'ai-agent', 'ai-tool',
+  'ai-vector-store', 'ai-memory', 'ai-training', 'ai-evaluation', 'ai-telemetry',
+  'backup', 'export', 'declared',
+]);
+
+/**
+ * A fresh DataFlowGraph v1 envelope with every required top-level key
+ * present. Callers overlay real content; every array starts empty and
+ * every nested object starts as `{}` except `scope.source`, which
+ * defaults to `'scan'` (a fixture builder must set it to `'fixture'`
+ * explicitly — the safe default assumes real analyzer output).
+ */
+export function emptyGraphEnvelope(overrides = {}) {
+  const { graphId, generatedAt, scope, ...rest } = overrides;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    graphId: graphId || null,
+    generatedAt: generatedAt || new Date().toISOString(),
+    scope: { source: 'scan', ...(scope || {}) },
+    scanHealth: {},
+    taxonomy: {},
+    nodes: [],
+    edges: [],
+    dataElements: [],
+    transformations: [],
+    flows: [],
+    controls: [],
+    policies: [],
+    evidence: [],
+    coverage: {},
+    limitations: [],
+    extensions: {},
+    ...rest,
+  };
+}