backend-skeleton 1.4.0 → 1.6.0

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];
+}

package/lib/impact-surface.mjs

@@ -0,0 +1,158 @@
+// D-cross-feature-impact-graph (D3): a feature's own public-surface projection + field-level change
+// detection, entirely git-independent (specs/ is commonly gitignored -- see D-contract-history's
+// own finding, which is why `bskel contract history`'s git-diff approach cannot be reused here).
+// *_shape_hash reuses lib/attest.mjs's canonicalization (K1) verbatim -- one implementation of
+// "what does it mean for two JSON values to be the same", not a second one that could disagree.
+import { readJsonIfExists, sha256File, sha256String, writeFileAtomic } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { canonicalize, assertCanonicalizable } from './attest.mjs';
+import { hydrateScanReportFilePaths } from './scan-report-paths.mjs';
+import { loadFieldDependencies, listDownstreamDependents } from './field-dependencies.mjs';
+
+const BASELINE_SCHEMA = 'sbf.impact-baseline/1';
+
+function shapeHash(schema) {
+	if (schema === undefined || schema === null || schema === false) return null;
+	assertCanonicalizable(schema);
+	return sha256String(canonicalize(schema));
+}
+
+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;
+}
+
+// D-cross-feature-impact-graph (D3): the current-moment surface for one feature, built entirely
+// from the already-emitted contract + already-persisted scan report + already-declared
+// dependencies.json -- zero new source scanning, zero live DB, zero LLM.
+export function computeSurface(root, featureId) {
+	const contract = readJsonIfExists(specPath(root, featureId, 'contracts', `${featureId}.schema.json`));
+	const operations = {};
+	for (const [opId, op] of Object.entries(contract?.operations ?? {})) {
+		operations[opId] = {
+			verb: op.verb ?? null,
+			path: op.path ?? null,
+			request_shape_hash: shapeHash(op.requestBodySchema),
+			response_shape_hash: shapeHash(op.responseSchema),
+			error_shape_hash: shapeHash(op.errorSchema),
+		};
+	}
+
+	const mod = ownDisposedModule(root, featureId);
+	const classes = mod ? [...(mod.entities ?? []), ...(mod.dtos ?? [])] : [];
+	const resources = {};
+	for (const cls of classes) {
+		resources[cls.className] = {
+			file_sha256: cls.file ? sha256File(cls.file) : null,
+			table: cls.table ?? null,
+			table_source: cls.tableSource ?? null,
+		};
+	}
+
+	// Deliberately sparse (D3's own stated limitation, mirroring D-field-dependency's EXIT): only
+	// fields SOMETHING has already named -- there is no per-adapter field enumerator to draw the
+	// full set from. Two directions, both needed: (a) fields THIS feature's own dependencies.json
+	// names as a TARGET (so removing/moving the file it depends on shows up on ITS OWN surface, for
+	// symmetry/debugging) and (b) fields OTHER features' dependencies.json name as THIS feature's
+	// SOURCE (via listDownstreamDependents() -- the exact reverse lookup describeDownstreamImpact()
+	// already uses) -- (b) is the one that actually matters for impact detection: it is what lets a
+	// change on the UPSTREAM/source feature's own `impact check` see "a field of mine that a
+	// downstream feature depends on just moved", not just the downstream feature seeing its own
+	// dependency go stale. Missing (b) would mean `field_source_moved` could only ever appear on the
+	// declaring (downstream) feature's own surface -- structurally unable to catch the upstream
+	// change this whole item exists to gate on. Found and fixed while writing this module's own
+	// headline test.
+	const deps = loadFieldDependencies(root, featureId);
+	const fields = {};
+	for (const dep of deps.dependencies) {
+		const resolved = classes.find((c) => c.className === dep.target.resourceType);
+		fields[`${dep.target.resourceType}.${dep.target.fieldName}`] = {
+			source_file_sha256: resolved?.file ? sha256File(resolved.file) : null,
+		};
+	}
+	for (const { dep } of listDownstreamDependents(root, featureId)) {
+		const key = `${dep.source.resourceType}.${dep.source.fieldName}`;
+		if (key in fields) continue;
+		const resolved = classes.find((c) => c.className === dep.source.resourceType);
+		fields[key] = { source_file_sha256: resolved?.file ? sha256File(resolved.file) : null };
+	}
+
+	return { operations, resources, fields };
+}
+
+export function impactBaselinePath(root, featureId) {
+	return specPath(root, featureId, 'impact-baseline.json');
+}
+
+export function loadBaseline(root, featureId) {
+	const p = impactBaselinePath(root, featureId);
+	const parsed = readJsonIfExists(p);
+	if (parsed === null) return null;
+	const { ok, errors } = validateAgainstSchema('impact-baseline.schema.json', parsed);
+	if (!ok) throw new Error(`${p}: does not match schemas/impact-baseline.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	return parsed;
+}
+
+export function saveBaseline(root, featureId, surface, { capturedAt = new Date().toISOString() } = {}) {
+	const doc = { schema: BASELINE_SCHEMA, feature_id: featureId, captured_at: capturedAt, surface };
+	const { ok, errors } = validateAgainstSchema('impact-baseline.schema.json', doc);
+	if (!ok) throw new Error(`refusing to write an invalid impact baseline for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	writeFileAtomic(impactBaselinePath(root, featureId), `${JSON.stringify(doc, null, 2)}\n`);
+	return doc;
+}
+
+// D-cross-feature-impact-graph (D3): field-level change KINDS, not a full structural diff --
+// naming what changed inside a subtree would need a real schema differ this project doesn't have
+// (see D3's own EXIT, framing a future structural differ as an additive refinement). Deliberately
+// no field_added/field_removed for the SAME reason computeSurface()'s `fields` is sparse: this
+// project cannot honestly enumerate a resource's full field set, so it cannot honestly claim one
+// was added or removed -- only that the file backing an ALREADY-DECLARED field moved
+// (`field_source_moved`).
+export function diffSurface(before, after) {
+	const b = before ?? { operations: {}, resources: {}, fields: {} };
+	const changes = [];
+
+	const opIds = new Set([...Object.keys(b.operations ?? {}), ...Object.keys(after.operations ?? {})]);
+	for (const opId of opIds) {
+		const prev = b.operations?.[opId];
+		const next = after.operations?.[opId];
+		if (!next) { changes.push({ kind: 'operation_removed', subject: opId, from: prev, to: null }); continue; }
+		if (!prev) { changes.push({ kind: 'operation_added', subject: opId, from: null, to: next }); continue; }
+		if (prev.verb !== next.verb) changes.push({ kind: 'operation_verb_changed', subject: opId, from: prev.verb, to: next.verb });
+		if (prev.path !== next.path) changes.push({ kind: 'operation_path_changed', subject: opId, from: prev.path, to: next.path });
+		if (prev.request_shape_hash !== next.request_shape_hash) changes.push({ kind: 'operation_request_shape_changed', subject: opId, from: prev.request_shape_hash, to: next.request_shape_hash });
+		if (prev.response_shape_hash !== next.response_shape_hash) changes.push({ kind: 'operation_response_shape_changed', subject: opId, from: prev.response_shape_hash, to: next.response_shape_hash });
+		if (prev.error_shape_hash !== next.error_shape_hash) changes.push({ kind: 'operation_error_shape_changed', subject: opId, from: prev.error_shape_hash, to: next.error_shape_hash });
+	}
+
+	const resourceTypes = new Set([...Object.keys(b.resources ?? {}), ...Object.keys(after.resources ?? {})]);
+	for (const type of resourceTypes) {
+		const prev = b.resources?.[type];
+		const next = after.resources?.[type];
+		if (!next) { changes.push({ kind: 'resource_removed', subject: type, from: prev, to: null }); continue; }
+		if (!prev) continue; // a brand-new resource has no downstream yet (nothing could depend on it before it existed)
+		if (prev.table !== next.table) changes.push({ kind: 'resource_table_changed', subject: type, from: prev.table, to: next.table });
+	}
+
+	const fieldKeys = new Set([...Object.keys(b.fields ?? {}), ...Object.keys(after.fields ?? {})]);
+	for (const key of fieldKeys) {
+		const prev = b.fields?.[key];
+		const next = after.fields?.[key];
+		if (!prev || !next) continue; // add/remove of a declared-dependency field is covered by the dependency's own gate, not this one
+		if (prev.source_file_sha256 !== next.source_file_sha256) changes.push({ kind: 'field_source_moved', subject: key, from: prev.source_file_sha256, to: next.source_file_sha256 });
+	}
+
+	return changes.map((c) => ({ ...c, change_key: changeKey(c) }));
+}
+
+// The anti-rubber-stamp key: embeds the NEW hash, so a disposition recorded for one shape can
+// never cover a LATER, different change to the same subject -- there is no wildcard by
+// construction, matching cross-feature-resolution.schema.json's own stated discipline.
+export function changeKey(change) {
+	const digest = sha256String(canonicalize({ kind: change.kind, subject: change.subject, to: change.to }));
+	return `${change.kind}:${change.subject}:${digest.slice(0, 12)}`;
+}