backend-skeleton 1.4.0 → 1.6.0

package/lib/impact.mjs

@@ -0,0 +1,286 @@
+// 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';
+
+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 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: now.toISOString(),
+				},
+			],
+		};
+		return saveImpactResolution(root, feature, next);
+	});
+}
+
+// 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;
+		return saveImpactResolution(root, from, upstreamResolution);
+	});
+}

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.4.0",
+  "version": "1.6.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

@@ -72,6 +72,55 @@ export function findClassOrRecordDeclaration(maskedText) {
 	return { keyword: m[1], name: m[2], index: m.index };
 }
 
+// D-spring-data-rest-adapter: interface-shaped counterpart to findClassOrRecordDeclaration()
+// above -- CLASS_OR_RECORD_RE is hard-gated to `class`/`record`, so a Spring Data repository
+// interface (`interface X extends JpaRepository<Widget, UUID>`) is never recognized by it. Only
+// the single common shape "interface Name extends Super<A, B>" is matched -- a second
+// extends-interface in a multi-interface list (e.g. `extends QuerydslPredicateExecutor<Widget>,
+// JpaRepository<Widget, UUID>`) is not found; the caller is expected to validate `superName`
+// against a known allow-list and fail closed rather than guess which listed interface is the real
+// Spring Data supertype. Operates on masked text.
+const INTERFACE_EXTENDS_RE = /(?:public\s+)?\binterface\s+(\w+)\s+extends\s+(\w+)/;
+
+export function findInterfaceExtendsDeclaration(maskedText) {
+	const m = maskedText.match(INTERFACE_EXTENDS_RE);
+	if (!m) return null;
+	const afterSuper = m.index + m[0].length;
+	let typeArgsStart = null;
+	let typeArgsEnd = null;
+	if (maskedText[afterSuper] === '<') {
+		const close = matchBalanced(maskedText, afterSuper, '<', '>');
+		if (close !== -1) {
+			typeArgsStart = afterSuper + 1;
+			typeArgsEnd = close;
+		}
+	}
+	return { name: m[1], superName: m[2], index: m.index, typeArgsStart, typeArgsEnd };
+}
+
+// D-spring-data-rest-adapter: depth-tracked top-level comma split on '<'/'>' only -- same
+// algorithm patch-strategy.mjs's own splitTopLevelParams() uses on '('/')' for a DTO constructor's
+// argument list. Reimplemented here rather than imported: patch-strategy.mjs lives under
+// handles/providers/java-spring/, a DOWNSTREAM consumer of this file -- importing from it here
+// would invert the dependency direction this codebase's module layout otherwise keeps one-way.
+export function splitTopLevelTypeArgs(argsText) {
+	const parts = [];
+	let depth = 0;
+	let start = 0;
+	for (let i = 0; i < argsText.length; i++) {
+		const ch = argsText[i];
+		if (ch === '<') depth++;
+		else if (ch === '>') depth--;
+		else if (ch === ',' && depth === 0) {
+			parts.push(argsText.slice(start, i).trim());
+			start = i + 1;
+		}
+	}
+	const last = argsText.slice(start).trim();
+	if (last !== '' || parts.length > 0) parts.push(last);
+	return parts.filter((p) => p !== '');
+}
+
 const WHITESPACE_RE = /^\s*/;
 // A2 Phase 2 (D-java-ast-helper): `[\w.]+`, not `\w+` -- found live while building the real
 // JavaParser/Symbol-Solver AST cross-check. A fully-qualified annotation
@@ -262,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;