backend-skeleton 1.5.0 → 1.7.0

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)}`;
+}

package/lib/impact.mjs

@@ -0,0 +1,334 @@
+// D-cross-feature-impact-graph (D5/D6): `bskel impact check` (report, read-mostly) / `bskel impact
+// accept` (decide, advances the baseline) / `bskel impact disposition` (compatible|migrate|waive) /
+// `bskel impact ack` (clears a migrate obligation on the DOWNSTREAM side). Mirrors
+// lib/cross-feature-collisions.mjs's own check/waive split and lib/field-dependencies.mjs's
+// DependencyOperationError pattern exactly -- one shared error vocabulary a CLI caller (and a
+// future HTTP caller, per D-http-serving-layer) both derive their own response shape from.
+import { readJsonIfExists, sha256File, writeFileAtomic } from './fsutil.mjs';
+import { specPath } from './paths.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from './schema-validate.mjs';
+import { listFeatures } from './featurelifecycle.mjs';
+import { withLockSync } from './lock.mjs';
+import { requireValidFeatureId } from './featureid.mjs';
+import { EXIT_CODES } from './exit-codes.mjs';
+import { buildImpactGraph } from './impact-graph.mjs';
+import { computeSurface, loadBaseline, saveBaseline, diffSurface } from './impact-surface.mjs';
+import { appendDecisionEvent } from './decision-log.mjs';
+
+const REPORT_SCHEMA = 'sbf.impact-report/1';
+const RESOLUTION_SCHEMA = 'sbf.impact-resolution/1';
+
+export class ImpactOperationError extends Error {
+	constructor(message, { httpStatus = 400, exitCode = EXIT_CODES.BAD_ARGS, reasonCode = 'BAD_ARGS' } = {}) {
+		super(message);
+		this.name = 'ImpactOperationError';
+		this.httpStatus = httpStatus;
+		this.exitCode = exitCode;
+		this.reasonCode = reasonCode;
+	}
+}
+
+function requireValidOr400(id) {
+	try {
+		requireValidFeatureId(id);
+	} catch (err) {
+		throw new ImpactOperationError(err.message, { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+}
+
+export function impactReportPath(root, featureId) {
+	return specPath(root, featureId, 'impact-report.json');
+}
+
+export function impactResolutionPath(root, featureId) {
+	return specPath(root, featureId, 'impact-resolution.json');
+}
+
+export function loadImpactResolution(root, featureId) {
+	const p = impactResolutionPath(root, featureId);
+	const parsed = readJsonIfExists(p);
+	if (parsed === null) return { schema: RESOLUTION_SCHEMA, feature_id: featureId, dispositions: [] };
+	const { ok, errors } = validateAgainstSchema('impact-resolution.schema.json', parsed);
+	if (!ok) throw new Error(`${p}: does not match schemas/impact-resolution.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	return parsed;
+}
+
+function saveImpactResolution(root, featureId, doc) {
+	const { ok, errors } = validateAgainstSchema('impact-resolution.schema.json', doc);
+	if (!ok) throw new Error(`refusing to write an invalid impact resolution for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	writeFileAtomic(impactResolutionPath(root, featureId), `${JSON.stringify(doc, null, 2)}\n`);
+	return doc;
+}
+
+function loadImpactReport(root, featureId) {
+	return readJsonIfExists(impactReportPath(root, featureId));
+}
+
+function saveImpactReport(root, featureId, doc) {
+	const { ok, errors } = validateAgainstSchema('impact-report.schema.json', doc);
+	if (!ok) throw new Error(`refusing to write an invalid impact report for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	writeFileAtomic(impactReportPath(root, featureId), `${JSON.stringify(doc, null, 2)}\n`);
+	return doc;
+}
+
+// Every OTHER feature's owner set for a graph node -- a table node's owner is derived from whoever
+// maps_to_table it (reverse lookup); every other node type already carries its own feature_id.
+function ownerFeaturesOf(graph, nodeId) {
+	const node = graph.nodes.find((n) => n.id === nodeId);
+	if (!node) return new Set();
+	if (node.feature_id) return new Set([node.feature_id]);
+	if (node.type === 'table') {
+		const owners = new Set();
+		for (const e of graph.edges) {
+			if (e.relation === 'maps_to_table' && e.target === nodeId) {
+				const r = graph.nodes.find((n) => n.id === e.source);
+				if (r?.feature_id) owners.add(r.feature_id);
+			}
+		}
+		return owners;
+	}
+	return new Set();
+}
+
+function changeSubjectNodeId(featureId, change) {
+	if (change.kind.startsWith('operation_')) return `${featureId}#${change.subject}`;
+	if (change.kind === 'field_source_moved') return `${featureId}::${change.subject}`;
+	// resource_removed / resource_table_changed -- subject is a bare resourceType
+	return `${featureId}::${change.subject}`;
+}
+
+// D-cross-feature-impact-graph: walks the graph from ONE change's own node outward one hop, over
+// the three relations that can name a real downstream consumer. `derives_from` only counts when
+// the changed node is the DEPENDED-ON side (edge.target) -- something reading FROM it, not the
+// other way around.
+function findOutboundImpacts(graph, subjectNodeId, ownFeatureId) {
+	const impacts = [];
+	for (const e of graph.edges) {
+		let counterpartId = null;
+		if (e.relation === 'derives_from' && e.target === subjectNodeId) counterpartId = e.source;
+		else if (e.relation === 'fk_references' && (e.source === subjectNodeId || e.target === subjectNodeId)) counterpartId = e.source === subjectNodeId ? e.target : e.source;
+		else if (e.relation === 'name_collides_with' && (e.source === subjectNodeId || e.target === subjectNodeId)) counterpartId = e.source === subjectNodeId ? e.target : e.source;
+		else continue;
+		for (const feat of ownerFeaturesOf(graph, counterpartId)) {
+			if (feat === ownFeatureId) continue;
+			impacts.push({ downstream_feature: feat, via: e.relation, basis: e.basis, confidence: e.confidence });
+		}
+	}
+	return impacts;
+}
+
+function isDispositionActive(d, nowMs) {
+	if (d.mode === 'waive') {
+		if (!d.expires_at) return false;
+		return Date.parse(d.expires_at) > nowMs;
+	}
+	if (d.mode === 'migrate') return true; // migrate stays "recorded" indefinitely -- clearing the BLOCK is acknowledged, tracked separately
+	return true; // compatible
+}
+
+function findDisposition(resolution, changeKey, downstreamFeature, nowMs) {
+	return (resolution.dispositions ?? []).find((d) => d.change_key === changeKey && d.downstream_feature === downstreamFeature && isDispositionActive(d, nowMs));
+}
+
+// D-cross-feature-impact-graph (D5): read-mostly -- computes the current surface, diffs it against
+// impact-baseline.json, walks the graph for each change, and writes impact-report.json. Never
+// advances the baseline (only acceptImpact() does).
+export function checkImpact(root, featureId, { now = new Date() } = {}) {
+	requireValidOr400(featureId);
+	const graph = buildImpactGraph(root, { nowIso: now.toISOString() });
+	const baseline = loadBaseline(root, featureId);
+	const currentSurface = computeSurface(root, featureId);
+	const changes = diffSurface(baseline?.surface ?? null, currentSurface);
+	const resolution = loadImpactResolution(root, featureId);
+
+	const outbound = [];
+	for (const change of changes) {
+		const subjectNodeId = changeSubjectNodeId(featureId, change);
+		for (const impact of findOutboundImpacts(graph, subjectNodeId, featureId)) {
+			const disp = findDisposition(resolution, change.change_key, impact.downstream_feature, now.getTime());
+			outbound.push({ change_key: change.change_key, downstream_feature: impact.downstream_feature, via: impact.via, basis: impact.basis, confidence: impact.confidence, disposition: disp?.mode ?? null });
+		}
+	}
+
+	// inbound: every OTHER feature's own resolution naming THIS feature as downstream, mode migrate, not yet acknowledged
+	const inbound = [];
+	for (const other of listFeatures(root)) {
+		if (other.feature_id === featureId) continue;
+		const otherResolution = loadImpactResolution(root, other.feature_id);
+		for (const d of otherResolution.dispositions ?? []) {
+			if (d.mode === 'migrate' && d.downstream_feature === featureId) {
+				inbound.push({ upstream_feature: other.feature_id, change_key: d.change_key, mode: 'migrate', tracked_by: d.tracked_by, acknowledged: Boolean(d.acknowledged) });
+			}
+		}
+	}
+
+	const unknowns = [];
+	if (!baseline) unknowns.push(`no impact-baseline.json for "${featureId}" yet -- every operation/resource reports as newly added, run \`bskel impact accept --feature ${featureId}\` to capture the first baseline`);
+
+	const report = {
+		schema: REPORT_SCHEMA,
+		feature_id: featureId,
+		generated_at: now.toISOString(),
+		baseline: { present: Boolean(baseline), captured_at: baseline?.captured_at ?? null },
+		changes,
+		outbound,
+		inbound,
+		unknowns,
+	};
+	saveImpactReport(root, featureId, report);
+	return { report, evaluation: evaluateImpacts(report) };
+}
+
+// D-cross-feature-impact-graph (D6): only a PROVEN, undisposed outbound impact blocks -- the
+// gate-fatigue control Codex's own review named as the risk to answer directly. An unacknowledged
+// inbound migrate obligation also blocks (the two-sided handshake).
+export function evaluateImpacts(report) {
+	const blockingOutbound = report.outbound.filter((o) => o.confidence === 'proven' && !o.disposition);
+	const blockingInbound = report.inbound.filter((i) => !i.acknowledged);
+	return {
+		blocking: blockingOutbound.length > 0 || blockingInbound.length > 0,
+		blockingOutbound,
+		blockingInbound,
+		heuristicOutbound: report.outbound.filter((o) => o.confidence === 'heuristic'),
+	};
+}
+
+// D-cross-feature-impact-graph (D5): the DECIDE half -- refuses (AWAITING_DISPOSITION) if any
+// proven outbound impact is undisposed or any inbound migration is unacknowledged; otherwise
+// atomically rewrites impact-baseline.json from the CURRENT surface. On a feature with no prior
+// baseline, `checkImpact` above already reports every operation as `operation_added` with zero
+// downstream impacts (nothing can depend on what didn't exist), so this captures trivially -- no
+// bootstrap special case.
+export function acceptImpact(root, featureId, { now = new Date() } = {}) {
+	requireValidOr400(featureId);
+	return withLockSync(root, 'state', () => {
+		const { report, evaluation } = checkImpact(root, featureId, { now });
+		if (evaluation.blocking) {
+			throw new ImpactOperationError(
+				`"${featureId}" has ${evaluation.blockingOutbound.length} undisposed proven outbound impact(s) and ${evaluation.blockingInbound.length} unacknowledged inbound migration(s) -- run \`bskel impact disposition\`/\`bskel impact ack\` first, or \`bskel gate force impact --feature ${featureId} --reason "..."\` to override (recorded in signed attestations)`,
+				{ httpStatus: 409, exitCode: EXIT_CODES.AWAITING_DISPOSITION, reasonCode: 'GATE_AWAITING_DISPOSITION' },
+			);
+		}
+		const surface = computeSurface(root, featureId);
+		const baseline = saveBaseline(root, featureId, surface, { capturedAt: now.toISOString() });
+		return { baseline, report };
+	});
+}
+
+// D-cross-feature-impact-graph (D6): records one of {compatible, migrate, waive} for exactly one
+// {change_key, downstream_feature} pair -- never a wildcard. `migrate` requires --tracked-by
+// (non-empty); `waive` requires --expires-days (a positive integer), reusing the SAME decay
+// posture D-waiver-expiry already ships for `contract waive`.
+export function recordDisposition(root, { feature, changeKey, downstreamFeature, mode, reason, trackedBy = null, expiresDays = null, now = new Date() }) {
+	requireValidOr400(feature);
+	requireValidOr400(downstreamFeature);
+	if (!reason || !reason.trim()) {
+		throw new ImpactOperationError('bskel impact disposition requires --reason "..." -- every disposition must be auditable', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+	if (!['compatible', 'migrate', 'waive'].includes(mode)) {
+		throw new ImpactOperationError(`--mode must be one of compatible|migrate|waive (got "${mode}")`, { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+	if (mode === 'migrate' && (!trackedBy || !trackedBy.trim())) {
+		throw new ImpactOperationError('--mode migrate requires --tracked-by "<issue/PR reference>" -- a migrate disposition with nothing to track is a no-op that looks like a decision', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+	let expiresAt = null;
+	if (mode === 'waive') {
+		if (!(Number.isInteger(expiresDays) && expiresDays > 0)) {
+			throw new ImpactOperationError('--mode waive requires --expires-days <N> (a positive integer) -- same decay posture as `contract waive --expires`', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+		}
+		expiresAt = new Date(now.getTime() + expiresDays * 24 * 60 * 60 * 1000).toISOString();
+	}
+
+	return withLockSync(root, 'state', () => {
+		const current = loadImpactResolution(root, feature);
+		const at = now.toISOString();
+		const next = {
+			schema: RESOLUTION_SCHEMA,
+			feature_id: feature,
+			dispositions: [
+				...current.dispositions.filter((d) => !(d.change_key === changeKey && d.downstream_feature === downstreamFeature)),
+				{
+					change_key: changeKey,
+					downstream_feature: downstreamFeature,
+					mode,
+					reason,
+					tracked_by: mode === 'migrate' ? trackedBy : null,
+					expires_at: expiresAt,
+					acknowledged: false,
+					acknowledged_at: null,
+					acknowledged_reason: null,
+					at,
+				},
+			],
+		};
+		const saved = saveImpactResolution(root, feature, next);
+		appendDecisionEvent(root, feature, {
+			kind: 'impact_disposition', action: 'record', at, reason, feature_id: feature,
+			subject: { change_key: changeKey, downstream_feature: downstreamFeature },
+			mode, expires_at: expiresAt, tracked_by: mode === 'migrate' ? trackedBy : null,
+		});
+		return saved;
+	});
+}
+
+// D-cross-feature-impact-graph (D6): the DOWNSTREAM feature's own acknowledgement of a `migrate`
+// obligation another feature recorded against it -- flips `acknowledged` on the UPSTREAM feature's
+// own resolution record (that's where the obligation lives; ack doesn't create a new file).
+export function acknowledgeInbound(root, { feature, from, changeKey, reason, now = new Date() }) {
+	requireValidOr400(feature);
+	requireValidOr400(from);
+	if (!reason || !reason.trim()) {
+		throw new ImpactOperationError('bskel impact ack requires --reason "..." -- every acknowledgement must be auditable', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+	return withLockSync(root, 'state', () => {
+		const upstreamResolution = loadImpactResolution(root, from);
+		const match = upstreamResolution.dispositions.find((d) => d.mode === 'migrate' && d.downstream_feature === feature && d.change_key === changeKey);
+		if (!match) {
+			throw new ImpactOperationError(`no "migrate" disposition from "${from}" targeting "${feature}" for change_key "${changeKey}" -- run \`bskel impact check --feature ${feature}\` to see current inbound obligations`, { httpStatus: 404, exitCode: EXIT_CODES.NOT_PASSED, reasonCode: 'MISSING_ARTIFACT' });
+		}
+		match.acknowledged = true;
+		match.acknowledged_at = now.toISOString();
+		match.acknowledged_reason = reason;
+		const saved = saveImpactResolution(root, from, upstreamResolution);
+		appendDecisionEvent(root, from, {
+			kind: 'impact_disposition', action: 'acknowledge', at: match.acknowledged_at, reason, feature_id: from,
+			subject: { change_key: changeKey, downstream_feature: feature },
+			mode: match.mode, expires_at: match.expires_at ?? null, tracked_by: match.tracked_by ?? null,
+		});
+		return saved;
+	});
+}
+
+// D-decision-event-log (D6): forward-only retraction, mirroring `gate revoke`'s own precedent --
+// removes the entry (its absence IS the state, matching every other withdraw in this item) and
+// appends a `withdraw` event carrying the reason. Never a snapshot restore: a disposition has no
+// "previous value" worth restoring once the change it covered has moved on -- see
+// D-decision-event-log's own Q4 answer in DECISIONS.md for why this is the correct
+// generalization of `gate revoke`, not of `lib/patch-transactions.mjs`'s preimage-blob rollback.
+export function withdrawDisposition(root, { feature, changeKey, downstreamFeature, reason, now = new Date() }) {
+	requireValidOr400(feature);
+	requireValidOr400(downstreamFeature);
+	if (!reason || !reason.trim()) {
+		throw new ImpactOperationError('bskel impact disposition --withdraw requires --reason "..." -- every withdrawal must be auditable', { httpStatus: 400, exitCode: EXIT_CODES.BAD_ARGS, reasonCode: 'BAD_ARGS' });
+	}
+	return withLockSync(root, 'state', () => {
+		const current = loadImpactResolution(root, feature);
+		const match = current.dispositions.find((d) => d.change_key === changeKey && d.downstream_feature === downstreamFeature);
+		if (!match) {
+			throw new ImpactOperationError(`no disposition recorded for change_key "${changeKey}" -> "${downstreamFeature}" on feature "${feature}" -- nothing to withdraw`, { httpStatus: 404, exitCode: EXIT_CODES.NOT_PASSED, reasonCode: 'MISSING_ARTIFACT' });
+		}
+		const at = now.toISOString();
+		const next = {
+			schema: RESOLUTION_SCHEMA,
+			feature_id: feature,
+			dispositions: current.dispositions.filter((d) => !(d.change_key === changeKey && d.downstream_feature === downstreamFeature)),
+		};
+		const saved = saveImpactResolution(root, feature, next);
+		appendDecisionEvent(root, feature, {
+			kind: 'impact_disposition', action: 'withdraw', at, reason, feature_id: feature,
+			subject: { change_key: changeKey, downstream_feature: downstreamFeature },
+			mode: match.mode, expires_at: match.expires_at ?? null, tracked_by: match.tracked_by ?? null,
+		});
+		return saved;
+	});
+}

package/lib/patch-kinds.mjs

@@ -9,6 +9,13 @@
 import { loadCatalogEntry } from '../stack/apply.mjs';
 import { planConfigApply, executeConfigApply, executeConfigRollback } from '../stack/config-apply.mjs';
 import { planDdlApply, executeDdlApply, executeDdlRollback, requiredConfirmValue } from '../scanners/db/ddl-apply.mjs';
+import {
+	planJavaSourceSplice,
+	executeJavaSpliceApply,
+	executeJavaSpliceRollback,
+	requiredConfirmValue as javaSpliceRequiredConfirmValue,
+	describeStaleness as javaSpliceDescribeStaleness,
+} from '../handles/providers/java-spring/source-splice.mjs';
 
 const PATCH_KINDS = {
 	'config-apply': {
@@ -32,6 +39,23 @@ const PATCH_KINDS = {
 		// for one that drops a table -- see requiredConfirmValue()'s own comment for why.
 		requiredConfirmValue,
 	},
+	// D-java-source-splice: params: {file, edits}. planFresh re-derives everything (node identity,
+	// hashes, rendered content) from the current on-disk file every time -- never trusts a stored
+	// render, exactly like the other two kinds.
+	'java-source-splice': {
+		planFresh: (root, params) => planJavaSourceSplice(root, params),
+		paramsFromTxn: (txn) => ({
+			file: txn.target.file,
+			edits: txn.target.edits.map(({ op, locator, replacement, statements, imports }) => ({ op, locator, replacement, statements, imports })),
+		}),
+		apply: executeJavaSpliceApply,
+		rollback: executeJavaSpliceRollback,
+		requiredConfirmValue: javaSpliceRequiredConfirmValue,
+		// Optional per-kind hook (absent on the other two kinds): consulted by bin/bskel.mjs's
+		// cmdPatchApprove/cmdPatchApply only when replanTransaction() throws StaleTransactionError,
+		// to name which edit moved and why -- never changes the engine's own pass/fail decision.
+		describeStaleness: javaSpliceDescribeStaleness,
+	},
 };
 
 export const PATCH_KIND_NAMES = Object.freeze(Object.keys(PATCH_KINDS));

package/lib/repo.mjs

@@ -98,3 +98,49 @@ export function isDirty(cwd = process.cwd()) {
 		return null;
 	}
 }
+
+// D-attestation-payload-completeness (K2): the CONTENT identity of HEAD, distinct from its commit
+// identity (headSha() above) -- `git rev-parse HEAD^{tree}`. Two commits with identical tree
+// content (e.g. one only changes the commit message, or is an empty --amend) share this value,
+// which is the right identity for "what code was this attestation actually about". null on
+// failure, same convention as every other helper in this file.
+export function headTreeSha(cwd = process.cwd()) {
+	try {
+		return git(['rev-parse', 'HEAD^{tree}'], cwd);
+	} catch {
+		return null;
+	}
+}
+
+// D-attestation-payload-completeness (K2): a sorted, capped, structured view of
+// `git status --porcelain=v1 -z` -- makes `isDirty()`'s bare boolean actionable inside a signed
+// payload (D4's dirty-tree refusal needs to SHOW what's dirty, not just assert that it is).
+// Returns null on git failure, matching isDirty()'s own null-on-failure posture. `-z` + NUL-split
+// is used (not the newline-delimited default) specifically because a renamed/copied path's
+// porcelain line legitimately contains no separator between old and new path other than NUL.
+export function worktreeStatus(cwd = process.cwd(), { cap = 200 } = {}) {
+	let raw;
+	try {
+		raw = execFileSync('git', ['status', '--porcelain=v1', '-z'], { cwd, encoding: 'utf8' });
+	} catch {
+		return null;
+	}
+	const fields = raw.split('\0').filter((f) => f.length > 0);
+	const entries = [];
+	for (let i = 0; i < fields.length; i++) {
+		const field = fields[i];
+		const status = field.slice(0, 2);
+		const path = field.slice(3);
+		// A rename/copy status ('R'/'C' in either column) is followed by a SEPARATE NUL-delimited
+		// field holding the ORIGINAL path -- consumed here (and dropped) so it isn't misread as its
+		// own status line; only the new path is reported, since `status` already discloses the move.
+		if (status[0] === 'R' || status[0] === 'C' || status[1] === 'R' || status[1] === 'C') i++;
+		entries.push({ status, path });
+	}
+	// Locale-independent, deterministic ordering -- Array.prototype.sort()'s default (UTF-16 code
+	// unit comparison) rather than localeCompare(), which varies by ICU data/host locale and would
+	// make the same repo state canonicalize to different signed bytes on different machines.
+	entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+	const truncated = entries.length > cap;
+	return { count: entries.length, truncated, entries: entries.slice(0, cap) };
+}

package/lib/workflow.mjs

@@ -44,6 +44,10 @@ const ESTABLISH_COMMAND = {
 	// directly on the first real stale occurrence and throws a raw TypeError instead of a clean
 	// stale report.
 	dependencies: (id) => `bskel dependency declare --feature ${id} --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."`,
+	// D-cross-feature-impact-graph (IG4): wired in the SAME commit as the `impact` gate itself,
+	// per every warning above in this file -- this exact gap has now been found live at least four
+	// times for other gates and is the single most reliably-recurring mistake in this module.
+	impact: (id) => `bskel impact check --feature ${id}   # then: bskel impact accept --feature ${id}`,
 	// D-business-rules (R7): wired in the SAME commit as the `rules` gate itself, per the repeated
 	// warnings above -- this exact gap has now been found live three times (dependencies,
 	// conformance, and the cross_feature near-miss) and is the single most reliably-recurring
@@ -72,6 +76,13 @@ function awaitingDispositionCommand(gateName, featureId) {
 	if (gateName === 'cross_feature') {
 		return `bskel scan cross-feature-waive --feature ${featureId} --signal resource_type|table|operation_id --identifier <name> --other-feature <id> --reason "..."   # or: bskel gate force cross_feature --feature ${featureId} --reason "..." if intentional`;
 	}
+	// D-cross-feature-impact-graph (IG5/IG6): `impact` reaches awaiting_disposition from
+	// `checkImpact()` finding an undisposed proven outbound impact or an unacknowledged inbound
+	// migration -- `bskel impact check`'s own output (not `bskel gate show`) names the exact
+	// change_key/downstream_feature pairs a human needs to pass to `disposition`/`ack`.
+	if (gateName === 'impact') {
+		return `bskel impact check --feature ${featureId} --json   # then: bskel impact disposition --feature ${featureId} --change <change_key> --downstream <id> --mode compatible|migrate|waive --reason "..."   # or: bskel gate force impact --feature ${featureId} --reason "..." if intentional`;
+	}
 	return `bskel gate force ${gateName} --feature ${featureId} --reason "..."`;
 }
 
@@ -98,6 +109,11 @@ const MUTATING_PREFIXES = [
 	// `rules emit` writes generated source. `rules list`/`rules explain` are read-only and
 	// correctly absent -- the same per-verb split `pattern list|show|suggest` was checked against.
 	'bskel rules check', 'bskel rules emit',
+	// D-cross-feature-impact-graph (IG4/IG5/IG6): `impact check` writes impact-report.json and can
+	// pass the gate; `impact accept` writes impact-baseline.json; `disposition`/`ack` write
+	// impact-resolution.json. `impact export` is deliberately absent -- read-only, spawns nothing,
+	// touches no gate (see IG8/IG9's own "never read back by a gate" guarantee).
+	'bskel impact check', 'bskel impact accept', 'bskel impact disposition', 'bskel impact ack',
 ];
 
 // Exported (not just inlined into action()) so lib/workflow.mjs's own test suite can assert the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",

package/scanners/adapters/_java-spring-analyzer.mjs

@@ -311,6 +311,12 @@ export function findMappingAnnotations(text) {
 			argsText: argsStart >= 0 ? text.slice(argsStart, argsEnd) : '',
 			methodName: sig.methodName,
 			methodLine: lineNumberAt(text, atIndex),
+			// D-resolver-policy-contract (PC8): the position right after ALL of this method's own
+			// annotations end (already computed above as `afterAnnotations`, just returned here too)
+			// -- the only way to carve a method region that contains every annotation regardless of
+			// source order (e.g. `@GetMapping(...) @PreAuthorize(...)`, where @PreAuthorize follows
+			// the mapping annotation instead of preceding it).
+			signatureIndex: afterAnnotations,
 		});
 	}
 	return results;