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

package/src/lineage/cross-repo-link.js

@@ -0,0 +1,107 @@
+// cross-repo-link.js — M5 deliverable #8 (FR-304's "declared" half only,
+// per the M5 top-level scoping doc's own DFG-025 row and this
+// deliverable's own scoping doc, 2026-09-02). The CrossRepoLink
+// extension contract — a graph-attached array (mirrors
+// `graph.recipientProfiles[]`'s own precedent, `recipient-profile.js`),
+// NEVER a DataFlowGraph v1 core-schema edge: `validate.js`'s
+// `_validateEdge` requires both endpoints of an edge to resolve against
+// the ONE graph's own `nodeIds` set, so a foreign node id from a
+// different repo's build can never pass `validateGraph()` — settling,
+// not merely motivating, the decision that a cross-repo link must be a
+// separate extension record.
+//
+// Mirrors `recipient-profile.js`'s own file shape exactly (pure module,
+// `{valid, errors}` validator, zero graph access at construction time),
+// with the one real, disclosed departure that module's own header also
+// discloses for itself: no per-field `fieldEvidence` map, since every
+// field on a CrossRepoLink is uniformly operator-declared (no
+// code-derived half) — closer to `ObligationMapping`'s single
+// record-level `factType` shape (here, `provenance`) than to
+// `RecipientProfile`'s per-field one.
+//
+// `provenance` reuses `schema.js`'s own `EDGE_PROVENANCE_VALUES` — this
+// deliverable's CLI is the FIRST real producer of `'manual'` anywhere in
+// this codebase (confirmed by the scoping investigation: every shipped
+// edge is `provenance: 'code'`, unconditionally, per Milestone 2
+// Sub-project F increment 1). `'schema'` stays reserved on the SAME
+// field for a future "imported"/auto-correlated producer (FR-304's
+// second flavor — destination/schema-based automatic cross-repo edge
+// correlation) — explicitly out of scope for this deliverable, per the
+// scoping doc's own "The real correction" section.
+
+import { EDGE_PROVENANCE_VALUES } from './schema.js';
+
+export const CROSS_REPO_LINK_VERSION = '1.0.0';
+
+// The operator-config filename this deliverable's CLI reads/writes,
+// resolved via `posture/state-dir.js`'s `statePath()` — mirrors
+// `recipient-registry.js`'s own `RECIPIENT_CONFIG_FILENAME` precedent.
+export const CROSS_REPO_LINKS_FILENAME = 'cross-repo-links.json';
+
+// Fixed, single legal value — mirrors `edge.relationship`'s own single
+// legal value ('data_flow', validate.js's `_validateEdge`). No new
+// taxonomy is introduced for this deliverable.
+export const CROSS_REPO_LINK_RELATIONSHIP = 'data_flow';
+
+function _isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
+function _isStringOrNull(v) { return v === null || v === undefined || typeof v === 'string'; }
+function _isPlainObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+
+// Shared endpoint-shape check for `local`/`remote` — `local` always
+// checks {graphId, graphDigest, nodeId}; `remote` additionally checks
+// {repository, sourceFile} via `extraFields`.
+function _validateEndpoint(endpoint, label, err, extraFields = []) {
+  if (!_isPlainObject(endpoint)) {
+    err(`$.${label}`, `${label} is required and must be an object`);
+    return;
+  }
+  if (!_isNonEmptyString(endpoint.graphId)) err(`$.${label}.graphId`, `${label}.graphId is required`);
+  if (!_isNonEmptyString(endpoint.graphDigest)) err(`$.${label}.graphDigest`, `${label}.graphDigest is required`);
+  if (!_isNonEmptyString(endpoint.nodeId)) err(`$.${label}.nodeId`, `${label}.nodeId is required`);
+  for (const field of extraFields) {
+    if (!_isNonEmptyString(endpoint[field])) err(`$.${label}.${field}`, `${label}.${field} is required`);
+  }
+}
+
+/**
+ * Structural validation only — mirrors `validateRecipientProfile`'s/
+ * `validateScenario`'s own `{valid, errors}` shape and "never throws"
+ * contract. Never confirms `local.nodeId`/`remote.nodeId` actually exist
+ * in any real graph — that needs real graph content, which this pure
+ * module deliberately has no access to (mirrors `scenario.js`'s own
+ * "structural-only, zero graph access" boundary exactly). That check is
+ * `federation-loader.js`'s (for the remote side) and the CLI's own
+ * `loadSignedGraph` call (for the local side) job, at declare time.
+ *
+ * @param {object} record
+ * @returns {{valid: boolean, errors: Array<{path: string, message: string}>}}
+ */
+export function validateCrossRepoLink(record) {
+  const errors = [];
+  const err = (p, message) => errors.push({ path: p, message });
+
+  if (!_isPlainObject(record)) {
+    err('$', 'CrossRepoLink record must be an object');
+    return { valid: false, errors };
+  }
+
+  if (!_isNonEmptyString(record.id) || !record.id.startsWith('crosslink:')) {
+    err('$.id', 'id is required and must start with "crosslink:"');
+  }
+  if (!_isNonEmptyString(record.version)) err('$.version', 'version is required');
+  if (!EDGE_PROVENANCE_VALUES.includes(record.provenance)) {
+    err('$.provenance', `unrecognized provenance "${record.provenance}" — must be one of ${EDGE_PROVENANCE_VALUES.join('|')}`);
+  }
+  if (record.relationship !== CROSS_REPO_LINK_RELATIONSHIP) {
+    err('$.relationship', `relationship must be "${CROSS_REPO_LINK_RELATIONSHIP}" (got "${record.relationship}")`);
+  }
+
+  _validateEndpoint(record.local, 'local', err);
+  _validateEndpoint(record.remote, 'remote', err, ['repository', 'sourceFile']);
+
+  if (!_isStringOrNull(record.rationale)) err('$.rationale', 'rationale must be a string or null');
+  if (!_isNonEmptyString(record.declaredBy)) err('$.declaredBy', 'declaredBy is required');
+  if (!_isNonEmptyString(record.declaredAt)) err('$.declaredAt', 'declaredAt is required');
+
+  return { valid: errors.length === 0, errors };
+}

package/src/lineage/dataflow-graph.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentic-security.dev/schemas/dataflow-graph/1.0.0.json",
+  "title": "DataFlowGraph v1",
+  "description": "Canonical application data-lineage graph contract (Data Flow Explorer PRD section 10). Renderer-independent; consumed by Architecture, Privacy, and Trace projections.",
+  "type": "object",
+  "required": ["schemaVersion", "graphId", "generatedAt", "scope", "scanHealth", "taxonomy", "nodes", "edges", "dataElements", "transformations", "flows", "controls", "policies", "evidence", "coverage", "limitations", "extensions"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "graphId": { "type": "string", "pattern": "^dfg:" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "scope": {
+      "type": "object",
+      "properties": {
+        "source": { "type": "string", "enum": ["scan", "fixture"] }
+      }
+    },
+    "scanHealth": { "type": "object" },
+    "taxonomy": { "type": "object" },
+    "nodes": { "type": "array", "items": { "$ref": "#/$defs/node" } },
+    "edges": { "type": "array", "items": { "$ref": "#/$defs/edge" } },
+    "dataElements": { "type": "array", "items": { "$ref": "#/$defs/dataElement" } },
+    "transformations": { "type": "array", "items": { "$ref": "#/$defs/transformation" } },
+    "flows": { "type": "array", "items": { "$ref": "#/$defs/flow" } },
+    "controls": { "type": "array" },
+    "policies": { "type": "array" },
+    "evidence": { "type": "array", "items": { "$ref": "#/$defs/evidence" } },
+    "coverage": { "type": "object" },
+    "limitations": { "type": "array" },
+    "extensions": { "type": "object" }
+  },
+  "$defs": {
+    "node": {
+      "type": "object",
+      "required": ["id", "kind", "label", "aliases", "system", "externality", "lifecycleStages", "governanceRefs", "dataElementIds", "evidenceRefs", "confidence", "coverageStatus"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^node:" },
+        "kind": { "type": "string", "enum": ["source", "process", "transform", "api", "store", "queue", "log", "sink", "external", "boundary", "unresolved"] },
+        "subtype": { "type": ["string", "null"] },
+        "label": { "type": "string" },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "location": { "type": ["object", "null"] },
+        "system": { "type": "object" },
+        "destination": { "type": ["object", "null"] },
+        "externality": {
+          "type": "object",
+          "properties": {
+            "value": { "type": "string", "enum": ["internal", "external", "unknown"] },
+            "evidenceRefs": { "type": "array", "items": { "type": "string" } }
+          }
+        },
+        "lifecycleStages": { "type": "array", "items": { "type": "string" } },
+        "governanceRefs": { "type": "object" },
+        "dataElementIds": { "type": "array", "items": { "type": "string" } },
+        "evidenceRefs": { "type": "array", "items": { "type": "string" } },
+        "confidence": { "type": "object" },
+        "coverageStatus": { "type": "string", "enum": ["modeled", "partial", "candidate", "unsupported", "manual"] }
+      }
+    },
+    "fieldMapping": {
+      "type": "object",
+      "required": ["fromPath", "toPath", "dataElementIds", "mappingType", "transformationIds"],
+      "properties": {
+        "fromPath": { "type": "string" },
+        "toPath": { "type": "string" },
+        "dataElementIds": { "type": "array", "items": { "type": "string" } },
+        "mappingType": { "type": "string", "enum": ["identity", "rename", "projection", "serialization", "deserialization", "transformation", "aggregation", "join", "filter", "sort", "conditional", "unknown"] },
+        "transformationIds": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "protocol": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "destinationResolution": { "type": "string", "enum": ["literal", "resolved_from_constant", "resolved_from_config", "resolved_from_schema", "declared_service", "runtime_corroborated", "dynamic", "unknown"] }
+      }
+    },
+    "protectionDimension": {
+      "type": "object",
+      "required": ["verdict", "evidenceGrade"],
+      "properties": {
+        "verdict": { "type": "string", "enum": ["protected", "unprotected", "unknown", "not_applicable", "not_assessed"] },
+        "evidenceGrade": { "type": "string", "enum": ["runtime", "code_and_config", "code", "config", "declared", "assumed", "manual", "none"] }
+      }
+    },
+    "edge": {
+      "type": "object",
+      "required": ["id", "from", "to", "relationship", "fieldMappings", "protocol", "boundaryCrossings", "provenance", "protection", "evidenceRefs", "coverageStatus"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^edge:" },
+        "from": { "type": "string" },
+        "to": { "type": "string" },
+        "relationship": { "const": "data_flow" },
+        "fieldMappings": { "type": "array", "items": { "$ref": "#/$defs/fieldMapping" } },
+        "protocol": { "$ref": "#/$defs/protocol" },
+        "boundaryCrossings": { "type": "array", "items": { "type": "string" } },
+        "provenance": { "type": "string", "enum": ["code", "schema", "manual", "runtime"] },
+        "protection": {
+          "type": "object",
+          "required": ["transit", "atRest", "handling"],
+          "properties": {
+            "transit": { "$ref": "#/$defs/protectionDimension" },
+            "atRest": { "$ref": "#/$defs/protectionDimension" },
+            "handling": { "$ref": "#/$defs/protectionDimension" }
+          }
+        },
+        "evidenceRefs": { "type": "array", "items": { "type": "string" } },
+        "coverageStatus": { "type": "string", "enum": ["modeled", "partial", "candidate", "unsupported", "manual"] }
+      }
+    },
+    "dataElement": {
+      "type": "object",
+      "required": ["id", "name", "aliases", "dataClasses", "aiContexts", "sourceLocations", "classificationEvidence", "manualOverride"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^data:" },
+        "name": { "type": "string" },
+        "aliases": { "type": "array", "items": { "type": "string" } },
+        "declaredType": { "type": ["string", "null"] },
+        "dataClasses": { "type": "array", "items": { "type": "string", "enum": ["PII", "PHI", "PCI", "FIN", "CREDENTIALS", "GEOLOCATION", "DEVICE_ID", "CONFIDENTIAL"] } },
+        "aiContexts": { "type": "array", "items": { "type": "string", "enum": ["ai.system_prompt", "ai.user_prompt", "ai.model_input", "ai.model_output", "ai.rag_context", "ai.embedding", "ai.vector_store", "ai.memory", "ai.tool_argument", "ai.tool_result", "ai.training_data", "ai.fine_tuning_data", "ai.evaluation_data", "ai.telemetry", "ai.model_artifact"] } },
+        "sourceLocations": { "type": "array" },
+        "dataSubjectCategory": { "type": ["string", "null"] },
+        "classificationEvidence": { "type": "array" },
+        "manualOverride": { "type": "boolean" },
+        "firstSeenProvenance": { "type": ["object", "null"] }
+      }
+    },
+    "transformation": {
+      "type": "object",
+      "required": ["id", "kind", "reversibility"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^transform:" },
+        "inputPath": { "type": "string" },
+        "outputPath": { "type": "string" },
+        "callee": { "type": "string" },
+        "location": { "type": ["object", "null"] },
+        "kind": { "type": "string", "enum": ["mask", "redact", "tokenize", "hash", "encrypt", "decrypt", "encode", "decode", "aggregate", "truncate", "normalize", "custom", "unknown"] },
+        "reversibility": { "type": "string", "enum": ["reversible", "irreversible", "unknown"] },
+        "algorithm": { "type": ["string", "null"] },
+        "appliesToAllPaths": { "type": ["boolean", "null"] },
+        "controlCredit": { "type": ["boolean", "null"] },
+        "controlCreditReason": { "type": ["string", "null"] }
+      }
+    },
+    "flow": {
+      "type": "object",
+      "required": ["id", "dataElementIds", "source", "sink", "edgeIds", "policyVerdict", "protectionSummary", "evidenceRefs", "coverageStatus"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^flow:" },
+        "dataElementIds": { "type": "array", "items": { "type": "string" } },
+        "source": { "type": "string" },
+        "sink": { "type": "string" },
+        "edgeIds": { "type": "array", "items": { "type": "string" } },
+        "transformationIds": { "type": "array", "items": { "type": "string" } },
+        "alternatePathCount": { "type": "integer", "minimum": 0 },
+        "policyVerdict": { "type": "string", "enum": ["prohibited", "permitted", "conditionally_permitted", "manual_review_required", "not_evaluated"] },
+        "protectionSummary": { "type": "string", "enum": ["protected", "unprotected", "mixed", "unknown", "not_assessed"] },
+        "evidenceRefs": { "type": "array", "items": { "type": "string" } },
+        "confidence": { "type": "object" },
+        "coverageStatus": { "type": "string", "enum": ["modeled", "partial", "candidate", "unsupported", "manual"] },
+        "findingRefs": { "type": "array" },
+        "governanceRefs": { "type": "object" },
+        "limitations": { "type": "array" }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["id", "claim", "evidenceType"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^evidence:" },
+        "claim": { "type": "string" },
+        "evidenceType": { "type": "string", "enum": ["code", "ir", "configuration", "iac", "schema", "service_declaration", "policy", "manual", "runtime"] },
+        "location": { "type": ["object", "null"] },
+        "producer": { "type": ["string", "null"] },
+        "confidenceTier": { "type": ["string", "null"] },
+        "snippet": { "type": ["string", "null"] },
+        "timestamp": { "type": ["string", "null"] },
+        "commit": { "type": ["string", "null"] },
+        "limitations": { "type": "array" },
+        "conflict": { "type": ["boolean", "null"] }
+      }
+    }
+  }
+}

package/src/lineage/decision-story.js

@@ -0,0 +1,206 @@
+// decision-story.js — M4 deliverable #7 (FR-501 §14, DFG-035): the
+// DecisionStory extension contract (§10.10) + a transparent 9-factor
+// ranking engine over real flows.
+//
+// Mirrors obligation-mapping.js's own shape exactly: a record is
+// explicitly NOT a DataFlowGraph v1 entity (§10.10 — "associated with,
+// but not required inside, the immutable base graph"), never added to
+// dataflow-graph.schema.json, never routed through validate.js.
+//
+// Ranking-factor availability, grounded in real investigation (see this
+// sub-project's own scoping doc): 7 of 9 factors are direct reads off
+// the graph, 1 (breadth) is a small new aggregation defined here, and 2
+// (recipientJurisdiction, changeRecency) are honestly `available: false`
+// on every flow — never fabricated, never silently dropped from the
+// factor list. recipientJurisdiction needs a RecipientProfile extension
+// (capability #6, not yet built); changeRecency needs GraphSnapshot/
+// GraphDiff (capability #3, Data-Flow Time Machine, not yet built).
+//
+// PRD's own binding constraint: "never represents an uncalibrated score
+// as expected financial loss or breach probability." This module NEVER
+// blends factors into a single opaque float — rankFlows performs a
+// documented, transparent, CONFIGURABLE (opts.factorOrder) multi-key
+// sort over each factor's own ordinal tier. Every factor stays
+// individually inspectable on the returned record.
+
+import { SEVERITY_RANK, DEFAULT_TAXONOMY } from '../dataflow/privacy-taxonomy.js';
+
+// The sink-registry categories (sink-registry.js's own CATEGORY_NODE_KIND
+// vocabulary) that count as an AI destination for the aiUse factor.
+// Exported so export-briefing.js's own "AI providers" chapter-3 listing
+// reads the SAME vocabulary rather than keeping a second, independently
+// drifting copy (Task 2 review finding, fixed).
+export const AI_SINK_SUBTYPES = Object.freeze(['ai-model-provider', 'ai-agent', 'ai-tool']);
+
+export const RANKING_FACTORS = Object.freeze([
+  'sensitivity', 'externality', 'controlVerdict', 'recipientJurisdiction',
+  'aiUse', 'breadth', 'evidenceConfidence', 'policyState', 'changeRecency',
+]);
+
+// Ordinal tier ranks, worst-first, used both to score a flow's own
+// factor and to compare two flows during rankFlows's own sort. Every
+// factor uses a SMALL, real, disclosed vocabulary — never a blended
+// number.
+const _TIER_RANK = {
+  sensitivity: { critical: 4, high: 3, medium: 2, low: 1, none: 0 },
+  externality: { external: 2, unknown: 1, internal: 0 },
+  controlVerdict: { unprotected: 4, mixed: 3, unknown: 2, not_assessed: 1, protected: 0, not_applicable: 0 },
+  recipientJurisdiction: { unknown: 0 },
+  aiUse: { ai_destination: 1, none: 0 },
+  breadth: { high: 2, medium: 1, low: 0 },
+  // Lower confidence is MORE attention-worthy (an uncertain flow needs
+  // review), so the tier rank is inverted relative to the raw score —
+  // disclosed here, not left implicit.
+  evidenceConfidence: { low: 2, medium: 1, high: 0 },
+  policyState: { prohibited: 4, manual_review_required: 3, conditionally_permitted: 2, not_evaluated: 1, permitted: 0 },
+  changeRecency: { unknown: 0 },
+};
+
+function _isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }
+function _isPlainObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); }
+function _isArray(v) { return Array.isArray(v); }
+
+/**
+ * Structural validation only — mirrors
+ * obligation-mapping.js#validateObligationMapping's own {valid, errors}
+ * shape and "never throws" contract.
+ */
+export function validateDecisionStory(record) {
+  const errors = [];
+  const err = (path, message) => errors.push({ path, message });
+
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    err('$', 'DecisionStory record must be an object');
+    return { valid: false, errors };
+  }
+  if (!_isNonEmptyString(record.id) || !record.id.startsWith('story:')) {
+    err('$.id', 'id is required and must start with "story:"');
+  }
+  if (!_isNonEmptyString(record.version)) err('$.version', 'version is required');
+  if (!_isNonEmptyString(record.audienceMode)) err('$.audienceMode', 'audienceMode is required');
+  if (!_isPlainObject(record.scopeQuery)) err('$.scopeQuery', 'scopeQuery is required and must be an object');
+  if (!_isArray(record.chapters)) err('$.chapters', 'chapters must be an array');
+  if (!_isArray(record.contributingGraphIds)) err('$.contributingGraphIds', 'contributingGraphIds must be an array');
+  if (!_isArray(record.rankingFactors)) err('$.rankingFactors', 'rankingFactors must be an array');
+  if (!_isNonEmptyString(record.evidenceGrade)) err('$.evidenceGrade', 'evidenceGrade is required');
+  if (!_isPlainObject(record.coverage)) err('$.coverage', 'coverage is required and must be an object');
+  if (!_isArray(record.decisions)) err('$.decisions', 'decisions must be an array');
+  if (!_isNonEmptyString(record.generatedAt)) err('$.generatedAt', 'generatedAt is required');
+  if (!_isNonEmptyString(record.graphDigest)) err('$.graphDigest', 'graphDigest is required');
+
+  return { valid: errors.length === 0, errors };
+}
+
+function _sensitivityFactor(flow, graph) {
+  const de = graph.dataElements.find((d) => flow.dataElementIds.includes(d.id));
+  const classes = de?.dataClasses ?? [];
+  if (classes.length === 0) return { available: true, tier: 'none', evidence: [] };
+  let worst = 'low';
+  for (const cls of classes) {
+    const sev = DEFAULT_TAXONOMY[cls]?.severity ?? 'medium';
+    if ((SEVERITY_RANK[sev] ?? 0) > (SEVERITY_RANK[worst] ?? 0)) worst = sev;
+  }
+  return { available: true, tier: worst, evidence: [de.id] };
+}
+
+function _externalityFactor(flow, nodesById) {
+  const sink = nodesById.get(flow.sink);
+  const value = sink?.externality?.value ?? 'unknown';
+  return { available: true, tier: value, evidence: [flow.sink] };
+}
+
+function _controlVerdictFactor(flow) {
+  return { available: true, tier: flow.protectionSummary ?? 'not_assessed', evidence: flow.edgeIds ?? [] };
+}
+
+function _recipientJurisdictionFactor() {
+  // Honest gap — see this file's own header. Never fabricated.
+  return { available: false, tier: 'unknown', evidence: [], unavailableReason: 'RecipientProfile extension not yet built (capability #6, Third-Party/Cross-Border Intelligence)' };
+}
+
+function _aiUseFactor(flow, nodesById) {
+  const sink = nodesById.get(flow.sink);
+  const isAi = AI_SINK_SUBTYPES.includes(sink?.subtype);
+  return { available: true, tier: isAi ? 'ai_destination' : 'none', evidence: isAi ? [flow.sink] : [] };
+}
+
+/**
+ * New small aggregation (the scoping doc's own "smallest real addition"
+ * for breadth/blast-radius): how many OTHER flows in the same graph
+ * share this flow's own sink node or dataElement. A crude but real,
+ * non-fabricated proxy for "how widely does this exposure reach" —
+ * never presented as a calibrated blast-radius count, just an ordinal
+ * tier over a real, disclosed count.
+ */
+function _breadthFactor(flow, graph) {
+  let sharedCount = 0;
+  for (const other of graph.flows) {
+    if (other.id === flow.id) continue;
+    const sharesSink = other.sink === flow.sink;
+    const sharesData = other.dataElementIds.some((id) => flow.dataElementIds.includes(id));
+    if (sharesSink || sharesData) sharedCount++;
+  }
+  const tier = sharedCount >= 5 ? 'high' : sharedCount >= 1 ? 'medium' : 'low';
+  return { available: true, tier, evidence: [], sharedFlowCount: sharedCount };
+}
+
+function _evidenceConfidenceFactor(flow) {
+  const tier = flow.confidence?.tier ?? 'medium';
+  return { available: true, tier, evidence: [] };
+}
+
+function _policyStateFactor(flow) {
+  return { available: true, tier: flow.policyVerdict ?? 'not_evaluated', evidence: flow.evidenceRefs ?? [] };
+}
+
+function _changeRecencyFactor() {
+  // Honest gap — see this file's own header. Never fabricated.
+  return { available: false, tier: 'unknown', evidence: [], unavailableReason: 'GraphSnapshot/GraphDiff not yet built (capability #3, Data-Flow Time Machine)' };
+}
+
+/** Score ONE flow on all 9 factors. Never throws on a well-formed graph. */
+export function scoreFlow(flow, graph, nodesById) {
+  return {
+    flowId: flow.id,
+    factors: {
+      sensitivity: _sensitivityFactor(flow, graph),
+      externality: _externalityFactor(flow, nodesById),
+      controlVerdict: _controlVerdictFactor(flow),
+      recipientJurisdiction: _recipientJurisdictionFactor(),
+      aiUse: _aiUseFactor(flow, nodesById),
+      breadth: _breadthFactor(flow, graph),
+      evidenceConfidence: _evidenceConfidenceFactor(flow),
+      policyState: _policyStateFactor(flow),
+      changeRecency: _changeRecencyFactor(),
+    },
+  };
+}
+
+/**
+ * Score and rank every flow in the graph. opts.factorOrder (default
+ * RANKING_FACTORS) is the PRD's own "transparent configurable factors"
+ * requirement, made real: a lexicographic multi-key sort over each
+ * factor's own ordinal tier rank, in the given priority order — NEVER a
+ * blended single score. Ties within all factors preserve original flow
+ * order (stable sort).
+ */
+export function rankFlows(graph, opts = {}) {
+  const factorOrder = opts.factorOrder ?? RANKING_FACTORS;
+  const nodesById = new Map(graph.nodes.map((n) => [n.id, n]));
+  const scored = graph.flows.map((flow) => ({
+    flow,
+    ...scoreFlow(flow, graph, nodesById),
+    factorOrderUsed: factorOrder,
+  }));
+  const rankOf = (scoredFlow, factor) => {
+    const f = scoredFlow.factors[factor];
+    return _TIER_RANK[factor]?.[f.tier] ?? 0;
+  };
+  return scored.sort((a, b) => {
+    for (const factor of factorOrder) {
+      const diff = rankOf(b, factor) - rankOf(a, factor);
+      if (diff !== 0) return diff;
+    }
+    return 0;
+  });
+}