backend-skeleton 1.5.0 → 1.7.0

package/lib/gate-export.mjs

@@ -0,0 +1,250 @@
+// D-attestation-payload-completeness: pure report-construction logic for `bskel gate export`,
+// pulled out of bin/bskel.mjs so it is unit-testable without spawning a CLI process -- the same
+// split lib/verify.mjs and lib/gates.mjs already follow (CLI stays thin, real logic lives in lib/).
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { GATE_NAMES, gateScopeId } from './gate-definitions.mjs';
+import { collectGateStatuses } from './verify.mjs';
+import { getGate, historyPath } from './state.mjs';
+import { requireNamedGate } from './gates.mjs';
+import { sha256File } from './fsutil.mjs';
+import { specPath, sbfPath } from './paths.mjs';
+import { crossFeatureReportPath, crossFeatureResolutionPath } from './cross-feature-collisions.mjs';
+import { dependenciesPath } from './field-dependencies.mjs';
+import { impactBaselinePath } from './impact-surface.mjs';
+import { impactReportPath, impactResolutionPath, loadImpactResolution } from './impact.mjs';
+import { manifestPath } from './handles-manifest.mjs';
+import { patchApprovalsPath, loadPatchApprovals } from './patch-approvals.mjs';
+import { loadResolution } from '../contracts/completeness.mjs';
+import { loadCrossFeatureResolution } from './cross-feature-collisions.mjs';
+import { decisionLogPath, readDecisionLog } from './decision-log.mjs';
+import { currentBranch, headSha, headTreeSha, worktreeStatus } from './repo.mjs';
+import { validateAgainstSchema } from './schema-validate.mjs';
+import { CANONICALIZATION_ID } from './attest.mjs';
+
+export const EXPORT_SCHEMA_VERSION = 'sbf.gate-export/4';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(__dirname, '..');
+
+let cachedToolVersion = null;
+// D-attestation-payload-completeness (K2): backend-skeleton's OWN package.json (this tool's
+// version), never the TARGET repo's -- resolved from this module's own file location, the same
+// derivation bin/bskel.mjs's SKILL_ROOT already uses. Memoized: it cannot change within one
+// process, and building one report already calls `sha256File`/git a dozen times.
+export function toolVersion() {
+	if (cachedToolVersion === null) {
+		cachedToolVersion = JSON.parse(fs.readFileSync(path.join(SKILL_ROOT, 'package.json'), 'utf8')).version;
+	}
+	return cachedToolVersion;
+}
+
+// S4 (D-gate-history), moved here from bin/bskel.mjs so both cmdGateHistory and
+// buildGateExportReport read history through one implementation instead of two copies that could
+// drift. Reads the append-only .sbf/<feature>.history.jsonl -- a corrupt/invalid line is skipped
+// with a warning, not a hard failure, matching JSONL's own resilience rationale (see
+// lib/state.mjs's appendGateEvent).
+export function readGateHistory(root, featureId, gateName, { onWarning } = {}) {
+	const file = historyPath(root, featureId);
+	if (!fs.existsSync(file)) return [];
+	const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+	const events = [];
+	for (const [i, line] of lines.entries()) {
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			onWarning?.(`${file}:${i + 1}: not valid JSON, skipped`);
+			continue;
+		}
+		const { ok, errors } = validateAgainstSchema('gate-event.schema.json', parsed);
+		if (!ok) {
+			onWarning?.(`${file}:${i + 1}: does not match schemas/gate-event.schema.json, skipped`, errors);
+			continue;
+		}
+		if (parsed.gate === gateName) events.push(parsed);
+	}
+	return events;
+}
+
+// D-attestation-payload-completeness (K2/K8): the ONE place an attestation-bound artifact is
+// declared -- adding a future artifact means adding one line here, the same single-source-of-
+// truth argument D-gate-definitions made for GATE_NAMES. Each value is (root, featureId) => an
+// absolute path; `test/gate-export-report.test.mjs` asserts this key set equals
+// `schemas/gate-export.schema.json`'s own `artifacts.properties` key set, so the two cannot drift.
+export const ARTIFACT_SOURCES = Object.freeze({
+	scan_report_hash: (root, featureId) => specPath(root, featureId, 'brownfield-scan.json'),
+	spec_hash: (root, featureId) => specPath(root, featureId, 'spec.md'),
+	contract_hash: (root, featureId) => specPath(root, featureId, 'contracts', `${featureId}.schema.json`),
+	contract_resolution_hash: (root, featureId) => specPath(root, featureId, 'contracts', `${featureId}.resolution.json`),
+	openapi_snapshot_hash: (root, featureId) => specPath(root, featureId, 'contracts', `${featureId}.openapi.snapshot.json`),
+	cross_feature_report_hash: (root, featureId) => crossFeatureReportPath(root, featureId),
+	cross_feature_resolution_hash: (root, featureId) => crossFeatureResolutionPath(root, featureId),
+	dependencies_hash: (root, featureId) => dependenciesPath(root, featureId),
+	rules_source_hash: (root, featureId) => specPath(root, featureId, 'rules.yaml'),
+	rules_compiled_hash: (root, featureId) => specPath(root, featureId, 'rules', `${featureId}.rules.json`),
+	conformance_report_hash: (root, featureId) => specPath(root, featureId, 'observe', `${featureId}.conformance-report.json`),
+	handles_manifest_hash: (root) => manifestPath(root),
+	stack_record_hash: (root) => sbfPath(root, 'stack.json'),
+	// D-cross-feature-impact-graph (IG4): additive, sbf.gate-export/2 -> /3 -- a /2 attestation
+	// still verifies (K7's own promise), it just won't have these three keys.
+	impact_baseline_hash: (root, featureId) => impactBaselinePath(root, featureId),
+	impact_report_hash: (root, featureId) => impactReportPath(root, featureId),
+	impact_resolution_hash: (root, featureId) => impactResolutionPath(root, featureId),
+	// D-decision-event-log (F3): patch-approvals.json was bound by NOTHING before this -- not a
+	// gate input, not an attestation artifact -- the exact same class of gap
+	// D-attestation-payload-completeness's finding #3 closed for .sbf/handles-manifest.json.
+	// sbf.gate-export/3 -> /4, additive (a /3 attestation still verifies, K7's own promise).
+	patch_approvals_hash: (root, featureId) => patchApprovalsPath(root, featureId),
+});
+
+export function collectArtifactHashes(root, featureId) {
+	const out = {};
+	for (const [key, resolvePath] of Object.entries(ARTIFACT_SOURCES)) {
+		out[key] = sha256File(resolvePath(root, featureId));
+	}
+	return out;
+}
+
+// D-attestation-payload-completeness (K2): forced/revoked decisions rolled up from the gate
+// records already in the payload -- zero new file reads. Waivers (contract_resolution/
+// cross_feature_resolution) are represented by presence+hash only, never embedded content: the
+// content is already bound via `artifacts` above, and embedding it again would duplicate that
+// binding while ballooning the payload for no new guarantee.
+// D-decision-event-log (D7): extended to cover all four spec-side decision files -- previously
+// only 2 of 4 appeared in waiver_files, and NONE of the four's live entries were represented at
+// all (only a hash). `records` mirrors gates.*.live's own "current vs live" distinction (K2):
+// each kind's entries here are LIVE-evaluated (expired contract/impact entries excluded), never
+// the raw stored array, so an expired-but-not-yet-renewed waiver never reads as still covering
+// its warning inside a signed attestation. `event_counts` rolls up the decision log -- present
+// even when a decision file itself is absent (an all-zero count is still informative: "no
+// decisions of this kind were ever made here", distinct from "the file doesn't exist").
+export function collectDecisions(root, featureId, gatesById, artifacts) {
+	const forced = [];
+	const revoked = [];
+	for (const [gate, entry] of Object.entries(gatesById)) {
+		const record = entry.current;
+		if (!record) continue;
+		if (record.forced) forced.push({ gate, scope: entry.scope, reason: record.reason ?? null, at: record.at ?? null });
+		if (record.status === 'revoked') revoked.push({ gate, scope: entry.scope, reason: record.reason ?? null, at: record.at ?? null });
+	}
+
+	const now = Date.now();
+	const contractResolution = loadResolution(root, featureId);
+	const liveContractWaivers = (contractResolution.waivers ?? [])
+		.filter((w) => !(typeof w.expires_at === 'string' && Date.parse(w.expires_at) <= now))
+		.map((w) => ({ code: w.code, subject: w.subject ?? null, reason: w.reason, at: w.at, expires_at: w.expires_at ?? null }));
+
+	const crossFeatureResolution = loadCrossFeatureResolution(root, featureId);
+	const liveCrossFeatureWaivers = (crossFeatureResolution.waivers ?? [])
+		.map((w) => ({ signal: w.signal, identifier: w.identifier, other_feature: w.other_feature, reason: w.reason, at: w.at }));
+
+	const impactResolution = loadImpactResolution(root, featureId);
+	const liveImpactDispositions = (impactResolution.dispositions ?? [])
+		.filter((d) => !(typeof d.expires_at === 'string' && Date.parse(d.expires_at) <= now))
+		.map((d) => ({ change_key: d.change_key, downstream_feature: d.downstream_feature, mode: d.mode, reason: d.reason, tracked_by: d.tracked_by ?? null, expires_at: d.expires_at ?? null, acknowledged: d.acknowledged ?? false }));
+
+	const patchApprovals = loadPatchApprovals(root, featureId);
+	const livePatchApprovals = (patchApprovals.approvals ?? [])
+		.map((a) => ({ resource: a.resource, field: a.field, strategy: a.strategy, reason: a.reason, at: a.at }));
+
+	const eventCounts = { contract_waiver: 0, cross_feature_waiver: 0, impact_disposition: 0, patch_approval: 0 };
+	for (const event of readDecisionLog(root, featureId)) {
+		if (Object.hasOwn(eventCounts, event.kind)) eventCounts[event.kind] += 1;
+	}
+
+	return {
+		forced,
+		revoked,
+		waiver_files: {
+			contract_resolution: { present: artifacts.contract_resolution_hash !== null, hash: artifacts.contract_resolution_hash },
+			cross_feature_resolution: { present: artifacts.cross_feature_resolution_hash !== null, hash: artifacts.cross_feature_resolution_hash },
+			impact_resolution: { present: artifacts.impact_resolution_hash !== null, hash: artifacts.impact_resolution_hash },
+			patch_approvals: { present: artifacts.patch_approvals_hash !== null, hash: artifacts.patch_approvals_hash },
+		},
+		records: {
+			contract_waivers: liveContractWaivers,
+			cross_feature_waivers: liveCrossFeatureWaivers,
+			impact_dispositions: liveImpactDispositions,
+			patch_approvals: livePatchApprovals,
+		},
+		event_counts: eventCounts,
+	};
+}
+
+// D-attestation-payload-completeness (K2/K3): pure derivation from `live` -- what a human or CI
+// actually greps for, so they read one line instead of walking every gate.
+export function buildVerdict(liveEntries) {
+	const blocking_gates = liveEntries.filter((g) => g.blocking).map((g) => g.gate);
+	const passing = liveEntries.filter((g) => g.status === 'pass' || g.status === 'pass (forced)').length;
+	return { blocking_gates, passing, total: liveEntries.length, ok: blocking_gates.length === 0 };
+}
+
+// D-attestation-payload-completeness (K2/K3): the report `bskel gate export` builds and (with
+// --sign) signs. `gates[name].live` is RECOMPUTED at export time via lib/verify.mjs's
+// collectGateStatuses() -- the exact same function `bskel verify` uses -- so a gate export and
+// `bskel verify` can never disagree about the same repo's current state. `gates[name].current`
+// stays the raw STORED record (unchanged from schema /1), so a reader sees both "what was last
+// written" and "what is honestly true right now" side by side.
+export function buildGateExportReport(root, featureId, { now = new Date(), dirtyAcknowledged = false, dirtyCap = 200 } = {}) {
+	const liveResults = collectGateStatuses(root, featureId, { getGate, requireNamedGate });
+	const liveByName = new Map(liveResults.map((g) => [g.gate, g]));
+
+	const gates = {};
+	for (const name of GATE_NAMES) {
+		const live = liveByName.get(name);
+		// collectGateStatuses()'s own `scope` field is the gate's DEFINITION scope type
+		// ('repo'|'feature'), not the resolved scope id -- gateScopeId() computes the real one
+		// (REPO_GATE_ID for a repo-scoped gate, or featureId itself), matching cmdGateExport's own
+		// pre-existing lookup exactly.
+		const scopeId = gateScopeId(name, featureId);
+		gates[name] = {
+			scope: scopeId,
+			current: getGate(root, scopeId, name),
+			history: readGateHistory(root, scopeId, name),
+			live: {
+				policy: live.policy,
+				status: live.status,
+				blocking: live.blocking,
+				ran: live.ran,
+				current_token: live.currentToken ?? null,
+				stale_reason: live.stale_reason ?? null,
+				changed_inputs: live.changed_inputs && live.changed_inputs.length > 0 ? live.changed_inputs : null,
+			},
+		};
+	}
+
+	const artifacts = collectArtifactHashes(root, featureId);
+	const decisions = collectDecisions(root, featureId, gates, artifacts);
+	const verdict = buildVerdict(Object.entries(gates).map(([gate, g]) => ({ gate, blocking: g.live.blocking, status: g.live.status })));
+
+	const status = worktreeStatus(root, { cap: dirtyCap });
+	const dirty = status === null ? null : status.count > 0;
+
+	return {
+		schema: EXPORT_SCHEMA_VERSION,
+		feature_id: featureId,
+		generated_at: now.toISOString(),
+		tool: {
+			name: 'bskel',
+			version: toolVersion(),
+			gate_names: [...GATE_NAMES],
+			canonicalization: CANONICALIZATION_ID,
+		},
+		git: {
+			branch: currentBranch(root),
+			head_sha: headSha(root),
+			dirty,
+			head_tree_sha: headTreeSha(root),
+			dirty_acknowledged: Boolean(dirtyAcknowledged),
+			dirty_file_count: status?.count ?? 0,
+			dirty_files_truncated: status?.truncated ?? false,
+			dirty_files: status?.entries ?? [],
+		},
+		artifacts,
+		gates,
+		decisions,
+		verdict,
+	};
+}

package/lib/impact-export-graphify.mjs

@@ -0,0 +1,145 @@
+// D-cross-feature-impact-graph (IG8/IG9): the ONE seam to the LLM-driven exploration layer -- writes
+// graphify's own extraction file shape (graphify.build.build_from_json's input contract), bypassing
+// its Steps 1-3 (install/detect/extract) entirely, so `bskel impact export --format graphify` needs
+// no LLM call, no subagent, no network. `impact-atlas` (or any other consumer) runs `build_from_json`
+// + `cluster` + `to_obsidian` on this file -- see DECISIONS.md's IG8 for the exact commands.
+//
+// The confidence mapping is the keystone: `proven` -> EXTRACTED, `heuristic` -> INFERRED. AMBIGUOUS
+// is NEVER emitted -- this graph has no guessed edges (see lib/impact-graph.mjs's own header), so
+// there is nothing honest to put there. A dedicated test (test/impact-export-graphify.test.mjs)
+// asserts this file's output against graphify's own real REQUIRED_NODE_FIELDS/REQUIRED_EDGE_FIELDS/
+// VALID_FILE_TYPES/VALID_CONFIDENCES constants, checked in as data -- the same "one declared place,
+// asserted equal" device D-attestation-payload-completeness's K8 uses for ARTIFACT_SOURCES.
+//
+// IG9 (Focus+Context, Lamping/Rao/Pirolli CHI'95): implemented as a DATA PROJECTION, not a renderer
+// -- `ring` (geodesic hop distance from --focus over the impact graph's own edges) and `detail`
+// (progressively coarser as ring grows) are computed here and written into the export ONLY, never
+// into anything a gate reads. Every downstream consumer (Obsidian's graph view, graphify's own
+// --html, Mermaid, Neo4j) inherits the same compression for free.
+const NODE_TYPE_TO_FILE_TYPE = { feature: 'document', operation: 'code', resource: 'code', table: 'document', field: 'code' };
+const RELATION_CONFIDENCE_SCORE = { EXTRACTED: 1.0, INFERRED: 0.7 };
+
+function graphifyConfidence(edgeConfidence) {
+	return edgeConfidence === 'proven' ? 'EXTRACTED' : 'INFERRED';
+}
+
+function sourceFileFor(node) {
+	if (node.file) return node.file;
+	if (node.type === 'feature') return `specs/${node.id}/feature.json`;
+	if (node.type === 'table') return '.sbf/impact-graph.json';
+	return '.sbf/impact-graph.json';
+}
+
+function nodeIdSafe(id) {
+	// graphify's own convention: lowercase, only [a-z0-9_] -- see its SKILL.md's Node ID format.
+	// bskel's own ids ("001-org::Organization", "001-org#getOrg") stay human-legible in `label`;
+	// this is only the graphify-facing id.
+	return id.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+}
+
+// BFS hop distance from `focusId` over the graph's edges treated as undirected -- Focus+Context
+// has no notion of edge direction, only "how far is this from what I'm looking at".
+function hopDistances(graph, focusId) {
+	const adj = new Map();
+	const link = (a, b) => { if (!adj.has(a)) adj.set(a, new Set()); adj.get(a).add(b); };
+	for (const e of graph.edges) { link(e.source, e.target); link(e.target, e.source); }
+	const dist = new Map([[focusId, 0]]);
+	const queue = [focusId];
+	while (queue.length > 0) {
+		const cur = queue.shift();
+		for (const next of adj.get(cur) ?? []) {
+			if (dist.has(next)) continue;
+			dist.set(next, dist.get(cur) + 1);
+			queue.push(next);
+		}
+	}
+	return dist;
+}
+
+function detailForRing(ring) {
+	if (ring === 0) return 'full';
+	if (ring === 1) return 'resource';
+	if (ring === 2) return 'feature';
+	return 'collapsed';
+}
+
+export function toGraphifyExtraction(graph, { focus = null, rings = null } = {}) {
+	let nodes = graph.nodes;
+	let edges = graph.edges;
+	let ringOf = null;
+
+	if (focus) {
+		const dist = hopDistances(graph, focus);
+		ringOf = dist;
+		if (Number.isInteger(rings)) {
+			const kept = [];
+			let collapsedCount = 0;
+			for (const n of graph.nodes) {
+				const d = dist.has(n.id) ? dist.get(n.id) : Infinity;
+				if (d <= rings) kept.push(n);
+				else collapsedCount++;
+			}
+			const keptIds = new Set(kept.map((n) => n.id));
+			const collapsedId = '__collapsed__';
+			const redirected = [];
+			const seenRedirect = new Set();
+			for (const e of graph.edges) {
+				const sIn = keptIds.has(e.source);
+				const tIn = keptIds.has(e.target);
+				if (sIn && tIn) { redirected.push(e); continue; }
+				if (!sIn && !tIn) continue; // both collapsed -- drop, nothing new to show
+				const kept_ = sIn ? e.source : e.target;
+				const key = `${kept_}->${collapsedId}`;
+				if (seenRedirect.has(key)) continue;
+				seenRedirect.add(key);
+				redirected.push({ source: sIn ? kept_ : collapsedId, target: sIn ? collapsedId : kept_, relation: e.relation, confidence: e.confidence, basis: e.basis });
+			}
+			nodes = collapsedCount > 0
+				? [...kept, { id: collapsedId, type: 'collapsed', label: `…${collapsedCount} more`, feature_id: null, file: null, attrs: { count: collapsedCount } }]
+				: kept;
+			edges = redirected;
+		}
+	}
+
+	const extractedNodes = nodes.map((n) => {
+		const ring = ringOf && n.id !== '__collapsed__' ? (ringOf.has(n.id) ? Math.min(ringOf.get(n.id), (rings ?? Infinity) + 1) : null) : null;
+		return {
+			id: nodeIdSafe(n.id),
+			label: n.label,
+			file_type: n.type === 'collapsed' ? 'document' : (NODE_TYPE_TO_FILE_TYPE[n.type] ?? 'document'),
+			source_file: n.type === 'collapsed' ? '.sbf/impact-graph.json' : sourceFileFor(n),
+			source_location: null,
+			sbf_type: n.type,
+			sbf_feature: n.feature_id,
+			...(focus ? { ring, detail: n.id === '__collapsed__' ? 'collapsed' : detailForRing(ring ?? 0) } : {}),
+			...(n.type === 'collapsed' ? { sbf_count: n.attrs.count } : {}),
+		};
+	});
+
+	const extractedEdges = edges.map((e) => {
+		const confidence = graphifyConfidence(e.confidence);
+		return {
+			source: nodeIdSafe(e.source),
+			target: nodeIdSafe(e.target),
+			relation: e.relation,
+			confidence,
+			confidence_score: RELATION_CONFIDENCE_SCORE[confidence],
+			source_file: e.basis?.artifact ?? '.sbf/impact-graph.json',
+			source_location: e.basis?.locator ?? null,
+			sbf_basis_sha256: e.basis?.artifact_sha256 ?? null,
+		};
+	});
+
+	return { nodes: extractedNodes, edges: extractedEdges, input_tokens: 0, output_tokens: 0 };
+}
+
+export function toMermaid(graph) {
+	const lines = ['graph LR'];
+	const safe = (id) => `"${id.replace(/"/g, '\'')}"`;
+	for (const n of graph.nodes) lines.push(`  ${nodeIdSafe(n.id)}[${safe(n.label)}]`);
+	for (const e of graph.edges) {
+		const arrow = e.confidence === 'proven' ? '-->' : '-.->';
+		lines.push(`  ${nodeIdSafe(e.source)} ${arrow}|${e.relation}| ${nodeIdSafe(e.target)}`);
+	}
+	return lines.join('\n');
+}

package/lib/impact-graph.mjs

@@ -0,0 +1,194 @@
+// D-cross-feature-impact-graph: builds the deterministic reference-links graph -- exact identities
+// only (contract operations, scan-report resourceTypes/tables, declared dependencies.json edges,
+// cross-feature-report.json findings), every one already hashed by an existing gate. Zero new
+// source-scanning: every fact here is read from a file some OTHER command already wrote and
+// validated. No `calls` relation, no inferred/guessed edge -- service-to-service and dynamic-client
+// dependency inference is Codex's own named boundary (see DECISIONS.md's EXIT list) and a missing
+// edge here is honest; a guessed one would be gate fatigue.
+//
+// Deliberately NOT called from lib/gate-definitions.mjs's `impact.recompute()` -- this does real
+// work (O(features x artifacts) file reads), which is exactly why the gate stays a pure
+// sha256File() token over impact-baseline.json/impact-report.json/impact-resolution.json instead.
+//
+// Scope cut from the original design (disclosed, not silent): a `handle` node type (UUID field
+// pointer, backed by `handles plan`'s live output) was planned but is NOT built in this pass --
+// `bskel handles plan` never persists a handles-plan.json (verified live: cmdHandlesPlan's own
+// comment says "that command never writes, dryRun always"), so producing a handle node here would
+// mean calling provider.plan() live inside a graph builder, with its own adapter-capability-gating
+// and error surface. Left as a named follow-up (see DECISIONS.md's EXIT list) rather than half-built.
+import path from 'node:path';
+import { readJsonIfExists, sha256File } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { listFeatures } from './featurelifecycle.mjs';
+import { hydrateScanReportFilePaths } from './scan-report-paths.mjs';
+import { loadFieldDependencies } from './field-dependencies.mjs';
+import { loadCrossFeatureReport } from './cross-feature-collisions.mjs';
+
+const IMPACT_GRAPH_SCHEMA = 'sbf.impact-graph/1';
+
+function ownDisposedModule(root, featureId) {
+	const report = hydrateScanReportFilePaths(readJsonIfExists(specPath(root, featureId, 'brownfield-scan.json')), root);
+	if (!report) return null;
+	const moduleName = report.disposition?.module ?? report.related_modules?.[0]?.module;
+	if (!moduleName) return null;
+	return report.related_modules?.find((m) => m.module === moduleName) ?? null;
+}
+
+function ownClasses(root, featureId) {
+	const mod = ownDisposedModule(root, featureId);
+	return mod ? [...(mod.entities ?? []), ...(mod.dtos ?? [])] : [];
+}
+
+function loadOwnContract(root, featureId) {
+	return readJsonIfExists(specPath(root, featureId, 'contracts', `${featureId}.schema.json`));
+}
+
+function resourceNodeId(featureId, resourceType) {
+	return `${featureId}::${resourceType}`;
+}
+
+function tableNodeId(tableName) {
+	return `table::${tableName.toLowerCase()}`;
+}
+
+function operationNodeId(featureId, opId) {
+	return `${featureId}#${opId}`;
+}
+
+function fieldNodeId(featureId, resourceType, fieldName) {
+	return `${featureId}::${resourceType}.${fieldName}`;
+}
+
+// Parses a `db_foreign_key` finding's flattened `"a.b -> c.d"` identifier back into its four parts
+// (the same shape flattenLiveForeignKeys()/findCollisions() in lib/cross-feature-collisions.mjs
+// composed it from -- there is no richer, unflattened form persisted anywhere to read instead).
+function parseFkIdentifier(identifier) {
+	const m = identifier.match(/^(.+)\.([^.]+) -> (.+)\.([^.]+)$/);
+	if (!m) return null;
+	return { table: m[1], column: m[2], referencesTable: m[3], referencesColumn: m[4] };
+}
+
+function confidenceOf(finding) {
+	return finding.confidence === 'high' ? 'proven' : 'heuristic';
+}
+
+// D-cross-feature-impact-graph (D2): the pure graph builder. Returns { schema, generated_at, nodes,
+// edges } matching schemas/impact-graph.schema.json. `nowIso` is injected (never Date.now()/`new
+// Date()` computed internally past this one seam) so callers -- and this module's own tests -- can
+// pin a deterministic generated_at.
+export function buildImpactGraph(root, { nowIso = new Date().toISOString() } = {}) {
+	const nodes = new Map();
+	const edges = [];
+	const addNode = (id, type, label, extra = {}) => {
+		if (!nodes.has(id)) nodes.set(id, { id, type, label, feature_id: extra.feature_id ?? null, file: extra.file ?? null, attrs: extra.attrs ?? {} });
+		return id;
+	};
+	const addEdge = (source, target, relation, confidence, basis) => {
+		edges.push({ source, target, relation, confidence, basis });
+	};
+	const relBasis = (root_, relPath, locator) => {
+		const abs = specPath(root_, ...relPath);
+		return { artifact: path.relative(root_, abs), artifact_sha256: sha256File(abs), locator };
+	};
+
+	const features = listFeatures(root);
+	const resourceTableOf = new Map(); // "<fid>::<Type>" -> table node id, for maps_to_table lookups below
+
+	for (const record of features) {
+		const fid = record.feature_id;
+		addNode(fid, 'feature', fid);
+
+		// operations, from the emitted contract
+		const contract = loadOwnContract(root, fid);
+		if (contract?.operations) {
+			const contractRel = path.relative(root, specPath(root, fid, 'contracts', `${fid}.schema.json`));
+			const contractSha = sha256File(specPath(root, fid, 'contracts', `${fid}.schema.json`));
+			for (const [opId, op] of Object.entries(contract.operations)) {
+				const nodeId = operationNodeId(fid, opId);
+				addNode(nodeId, 'operation', opId, { feature_id: fid, attrs: { verb: op.verb ?? null, path: op.path ?? null } });
+				addEdge(fid, nodeId, 'declares_operation', 'proven', { artifact: contractRel, artifact_sha256: contractSha, locator: `operations.${opId}` });
+			}
+		}
+
+		// resources (+ their table mapping), from the disposed scan-report module
+		for (const cls of ownClasses(root, fid)) {
+			const nodeId = resourceNodeId(fid, cls.className);
+			const rel = cls.file ? path.relative(root, cls.file) : null;
+			addNode(nodeId, 'resource', cls.className, { feature_id: fid, file: rel, attrs: { table: cls.table ?? null, table_source: cls.tableSource ?? null } });
+			const scanRel = path.relative(root, specPath(root, fid, 'brownfield-scan.json'));
+			const scanSha = sha256File(specPath(root, fid, 'brownfield-scan.json'));
+			addEdge(fid, nodeId, 'owns_resource', 'proven', { artifact: scanRel, artifact_sha256: scanSha, locator: `related_modules[].entities|dtos[className=${cls.className}]` });
+			if (cls.table) {
+				const tId = tableNodeId(cls.table);
+				addNode(tId, 'table', cls.table.toLowerCase());
+				const confidence = cls.tableSource === 'explicit' ? 'proven' : 'heuristic';
+				addEdge(nodeId, tId, 'maps_to_table', confidence, { artifact: scanRel, artifact_sha256: scanSha, locator: `related_modules[].entities[className=${cls.className}].table` });
+				resourceTableOf.set(nodeId, tId);
+			}
+		}
+
+		// fields, and derives_from edges -- only fields a declared dependency already named
+		const deps = loadFieldDependencies(root, fid);
+		if (deps.dependencies.length > 0) {
+			const depsRel = path.relative(root, specPath(root, fid, 'dependencies.json'));
+			const depsSha = sha256File(specPath(root, fid, 'dependencies.json'));
+			for (const dep of deps.dependencies) {
+				const targetId = fieldNodeId(fid, dep.target.resourceType, dep.target.fieldName);
+				const sourceId = fieldNodeId(dep.source.feature, dep.source.resourceType, dep.source.fieldName);
+				addNode(targetId, 'field', `${dep.target.resourceType}.${dep.target.fieldName}`, { feature_id: fid });
+				addNode(sourceId, 'field', `${dep.source.resourceType}.${dep.source.fieldName}`, { feature_id: dep.source.feature });
+				addEdge(targetId, sourceId, 'derives_from', 'proven', { artifact: depsRel, artifact_sha256: depsSha, locator: `dependencies[target.fieldName=${dep.target.fieldName}]` });
+			}
+		}
+	}
+
+	// cross-feature findings: fk_references + name_collides_with (resource_type/operation_id only --
+	// a `table` collision is already visible structurally, as two resources' maps_to_table edges
+	// converging on the same shared table:: node, so a redundant collision edge is skipped there).
+	for (const record of features) {
+		const fid = record.feature_id;
+		const report = loadCrossFeatureReport(root, fid);
+		if (!report?.findings) continue;
+		const reportRel = path.relative(root, specPath(root, fid, 'cross-feature-report.json'));
+		const reportSha = sha256File(specPath(root, fid, 'cross-feature-report.json'));
+
+		for (const finding of report.findings) {
+			if (finding.signal === 'db_foreign_key') {
+				const parsed = parseFkIdentifier(finding.identifier);
+				if (!parsed) continue;
+				const childId = tableNodeId(parsed.table);
+				const parentId = tableNodeId(parsed.referencesTable);
+				addNode(childId, 'table', parsed.table.toLowerCase());
+				addNode(parentId, 'table', parsed.referencesTable.toLowerCase());
+				addEdge(childId, parentId, 'fk_references', confidenceOf(finding), { artifact: reportRel, artifact_sha256: reportSha, locator: `findings[signal=db_foreign_key,identifier=${finding.identifier}]` });
+			} else if (finding.signal === 'resource_type') {
+				const ownId = resourceNodeId(fid, finding.identifier);
+				const otherId = resourceNodeId(finding.other_feature, finding.identifier);
+				if (nodes.has(ownId) && nodes.has(otherId)) {
+					addEdge(ownId, otherId, 'name_collides_with', confidenceOf(finding), { artifact: reportRel, artifact_sha256: reportSha, locator: `findings[signal=resource_type,identifier=${finding.identifier}]` });
+				}
+			} else if (finding.signal === 'operation_id') {
+				const ownId = operationNodeId(fid, finding.identifier);
+				const otherId = operationNodeId(finding.other_feature, finding.identifier);
+				if (nodes.has(ownId) && nodes.has(otherId)) {
+					addEdge(ownId, otherId, 'name_collides_with', confidenceOf(finding), { artifact: reportRel, artifact_sha256: reportSha, locator: `findings[signal=operation_id,identifier=${finding.identifier}]` });
+				}
+			}
+		}
+	}
+
+	return { schema: IMPACT_GRAPH_SCHEMA, generated_at: nowIso, nodes: [...nodes.values()], edges };
+}
+
+// D-cross-feature-impact-graph: one-hop reverse lookup -- every downstream feature whose
+// dependencies.json names a (featureId, resourceType) pair on the SOURCE side, i.e. depends on it.
+// Used by lib/impact.mjs's outbound-impact walk; kept here (not in lib/impact.mjs) since it is a
+// pure graph query, not a check/accept/disposition operation.
+export function downstreamFeaturesOf(graph, resourceOrOperationNodeId, relation) {
+	const out = new Set();
+	for (const edge of graph.edges) {
+		if (edge.relation !== relation) continue;
+		if (edge.target === resourceOrOperationNodeId) out.add({ featureNodeId: edge.source, edge });
+	}
+	return [...out];
+}