backend-skeleton 1.4.0 → 1.5.0

package/contracts/emit.mjs

@@ -15,12 +15,12 @@ import { pathPrefixCandidates, unreflectedPathPrefixes } from './export.mjs';
 // a path param. Direction stays one-way (openapi.mjs imports from emit.mjs, never the reverse).
 export const BARE_UUID_PATTERN = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$';
 
-// A7/A8/A9/A10: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
+// A7/A8/A9/A10/X2: the single source of truth for schemas/feature-contract.schema.json's `sbf_contract`
 // const -- bin/bskel.mjs's loadContract() imports this too, so the friendly "re-emit with the
-// current bskel" message and the value actually written here cannot drift apart. Bumped "7" -> "8"
-// for this item (sourceDescription) -- again cheap, the friendly re-emit pre-check needs zero
-// code change -- see D-openapi-description.
-export const CONTRACT_SCHEMA_VERSION = '8';
+// current bskel" message and the value actually written here cannot drift apart. Bumped "8" -> "9"
+// for this item (the `expansion` field, D-route-expansion-provenance) -- again cheap, the friendly
+// re-emit pre-check needs zero code change.
+export const CONTRACT_SCHEMA_VERSION = '9';
 
 // A9 (D-openapi-path-params): `sourcePathParamSchemas` (a Map<name, schema>, contracts/openapi.mjs's
 // applyPathParameterSchemas -- present only for a matched/adopted operation whose source document
@@ -66,7 +66,11 @@ function pathParamsSchema(routePath, sourcePathParamSchemas = null) {
 // Object>>`) -- findMethodParams() shares the same balanced-delimiter analyzer that fixes the
 // scanner's identical GenericWithSpaceController case.
 function detectRequestBody(filePath, methodName) {
-	if (!filePath || !fs.existsSync(filePath)) return null;
+	// X5 (D-route-expansion-provenance): explicit guard, not the incidental fact that a regex built
+	// from the literal string "null" also happens not to match anything -- a null methodName means
+	// there is genuinely no literal per-action source method to look in (see the same reasoning
+	// D-typescript-express-inline-handlers already established for resolveHandlerFile()).
+	if (!filePath || !methodName || !fs.existsSync(filePath)) return null;
 	const text = fs.readFileSync(filePath, 'utf8');
 	const params = findMethodParams(text, methodName);
 	if (params === null) return null;
@@ -377,6 +381,15 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 					}));
 				}
 				const { pathParams, pathParamsHeuristic } = pathParamsSchema(route, pathParamSchemas);
+				// X2 (D-route-expansion-provenance): present only when the scan adapter recorded which
+				// multi-route declaration this endpoint came from (ep.declarationIndex) AND that
+				// declaration actually resolves on the owning controller -- omitted for every ordinary
+				// 1:1 endpoint, the same "absent unless it applies" discipline A9's pathParamsHeuristic
+				// already established. No adapter populates declarationIndex yet (forward-compatible
+				// shape only) -- see test/contract.test.mjs's expansion-field tests for a hand-built
+				// fixture exercising this.
+				const declaration = ep.declarationIndex != null ? (controller.declarations?.[ep.declarationIndex] ?? null) : null;
+				const expansion = declaration ? { rule: declaration.rule, declarationLine: declaration.line, label: declaration.label ?? null } : null;
 				operations[operationId] = {
 					verb,
 					path: route,
@@ -397,6 +410,9 @@ export function buildContract({ featureId, featureUid, scanReport, module: modul
 					...(sourceRequestBody ? { sourceRequestBody } : {}),
 					// A9: omitted (not []) when every segment resolved from source, or the route has none.
 					...(pathParamsHeuristic ? { pathParamsHeuristic } : {}),
+					// X2: omitted entirely when this endpoint wasn't expanded from a multi-route
+					// declaration -- see the computation above.
+					...(expansion ? { expansion } : {}),
 					// A10: omitted entirely when --descriptions was not passed, the source had none, or
 					// it failed the length cap -- same "omitted, never null/false" discipline as every
 					// other field above.

package/handles/providers/java-spring/plan.mjs

@@ -25,7 +25,13 @@ function findFetchOperation(controllers, entityClassName) {
 			if (ep.verb !== 'GET' || !ep.operationId) continue;
 			const suffix = ep.path.slice(controller.basePath.length);
 			if (/^\/\{[^/]+\}$/.test(suffix)) {
-				return { operationId: ep.operationId, method: ep.method, path: ep.path, controllerFile: controller.file, controllerClassName: controller.className };
+				// X5 (D-route-expansion-provenance): threaded through so the caller can name the real
+				// cause when ep.method is null instead of a bare "method not found" message -- a 1:N
+				// framework-synthesized route (e.g. Spring Data REST) has a real operationId but no
+				// literal per-action method to correlate to. null on every endpoint in today's adapter
+				// (it never populates declarationIndex) -- forward-compatible only, not yet reachable.
+				const declaration = ep.declarationIndex != null ? (controller.declarations?.[ep.declarationIndex] ?? null) : null;
+				return { operationId: ep.operationId, method: ep.method, path: ep.path, controllerFile: controller.file, controllerClassName: controller.className, declaration };
 			}
 		}
 	}
@@ -282,6 +288,12 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 		}
 
 		const fetchOp = findFetchOperation(targetModule.controllers, entity.className);
+		// X5 (D-route-expansion-provenance): a real, already-fail-closed case, checked explicitly
+		// instead of relying on findRequiredAuthority()/countServiceMethodParams()'s own `!methodName`
+		// guards to silently swallow it -- those guards return safely (no crash) either way, but
+		// without this check the notes below would read literally "...found for X.null" / "could not
+		// find a null(...) method", which is confusing, not honest. See D-resolver-scope.
+		const fetchOpMissingMethod = Boolean(fetchOp && !fetchOp.method);
 		const authorityResult = findRequiredAuthority(fetchOp?.controllerFile ?? null, fetchOp?.method ?? null);
 		const requiredAuthority = authorityResult.authority;
 		const service = pkIsNonUuid ? null : findServiceFile(javaSrcRoot, targetModule.module, entity.className);
@@ -300,6 +312,12 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 
 		if (!fetchOp) {
 			notes.push(`${entity.className}: no single-resource GET endpoint found on a controller whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
+		} else if (fetchOpMissingMethod) {
+			const declaration = fetchOp.declaration;
+			const declNote = declaration
+				? ` -- it was expanded from ${declaration.label ?? declaration.rule} at ${path.relative(javaSrcRoot, fetchOp.controllerFile)}:${declaration.line} (rule: ${declaration.rule}); the framework generates this handler at runtime, so no literal per-action source method exists to correlate to`
+				: ' -- no literal per-action source method exists to correlate to';
+			notes.push(`${entity.className}: the matched endpoint (GET ${fetchOp.path})${declNote}. Resolver NOT generated -- this is a structural boundary of static-scan-based handles codegen, not a bug. See D-resolver-scope.`);
 		} else if (authorityResult.unsupported) {
 			notes.push(`${entity.className}: @PreAuthorize found on ${fetchOp.controllerClassName}.${fetchOp.method} (or its class) but not in the simple hasRole('X')/hasAuthority('X') shape this scanner understands (e.g. hasAnyRole/SpEL) -- requiredAuthority() defaults to "TODO_ROLE" (fails closed) until a human fixes it`);
 		} else if (!requiredAuthority) {
@@ -316,12 +334,15 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 			if (!pkIsNonUuid) {
 				notes.push(`${entity.className}: no ${entity.className}Service found under domain/${targetModule.module}/application/ or ${targetModule.module}/ -- resolver NOT generated for this entity (would produce a broken import). Emit it by hand once the right service is identified.`);
 			}
-		} else if (fetchOp && serviceParamCount !== 1) {
+		} else if (fetchOp && !fetchOpMissingMethod && serviceParamCount !== 1) {
 			const reason = serviceParamCount === null
 				? `could not find a ${fetchOp.method}(...) method on ${service.serviceType} to confirm its argument count`
 				: `${service.serviceType}.${fetchOp.method} takes ${serviceParamCount} argument(s), not the single resource UUID the generated resolver always passes`;
 			notes.push(`${entity.className}: ${reason} -- resolver NOT generated (would either fail to compile or silently call the wrong overload and drop a required scoping argument, e.g. an organization/cohort id). Wire it by hand -- ResourceResolver#fetch/#patchField receive the request's Authentication (D-resolver-authentication-context) for exactly this case, e.g. deriving a tenant/org id the same way the resource's own controller already does.`);
 		}
+		// X5: fetchOpMissingMethod already pushed its own single, clear note above -- suppressing
+		// this one avoids a second, confusing "could not find a null(...) method" note for the same
+		// root cause.
 
 		// A3 (D-patch-strategy): only worth computing once fetch()/the resolver itself is actually
 		// going to be generated -- an entity with no resolver has nowhere for patchField() codegen
@@ -447,7 +468,7 @@ export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter
 		module: inner.module,
 		resources: inner.resources.map((r) => ({
 			...r,
-			readPath: (r.service && r.fetchOperation) ? `${r.service.serviceType}.${r.fetchOperation.method}()` : null,
+			readPath: (r.service && r.fetchOperation && r.fetchOperation.method) ? `${r.service.serviceType}.${r.fetchOperation.method}()` : null,
 		})),
 		notes: inner.notes,
 	};

package/handles/providers/typescript-express/plan.mjs

@@ -57,7 +57,13 @@ function findFetchRoute(controllers, entityClassName) {
 			if (ep.verb !== 'GET') continue;
 			const suffix = ep.path.slice(controller.basePath.length);
 			if (/^\/:[^/(]+(\([^)]*\))?$/.test(suffix)) {
-				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className };
+				// X5 (D-route-expansion-provenance): threaded through so the caller can distinguish
+				// "inline arrow handler" (this provider's real, current no-method case) from "1:N
+				// framework-synthesized route" (a declaration is present) in its note text. null on
+				// every endpoint in today's adapter (it never populates declarationIndex) --
+				// forward-compatible only, not yet reachable.
+				const declaration = ep.declarationIndex != null ? (controller.declarations?.[ep.declarationIndex] ?? null) : null;
+				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className, declaration };
 			}
 		}
 	}
@@ -183,7 +189,14 @@ export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter
 		if (!fetchRoute) {
 			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
 		} else if (!fetchRoute.method) {
-			notes.push(`${entity.className}: the single-resource GET route's handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.`);
+			// X5 (D-route-expansion-provenance): a declaration means this route was expanded from a
+			// 1:N framework construct (no literal per-action method exists at all, not yet reachable
+			// in this adapter); no declaration keeps this provider's own real, current cause (an
+			// inline arrow-function handler) unchanged.
+			const note = fetchRoute.declaration
+				? `the matched endpoint (GET ${fetchRoute.path}) was expanded from ${fetchRoute.declaration.label ?? fetchRoute.declaration.rule} at ${path.relative(repoRoot, fetchRoute.file)}:${fetchRoute.declaration.line} (rule: ${fetchRoute.declaration.rule}) -- the framework generates this handler at runtime, so no literal per-action source method exists to correlate to. Resolver NOT generated -- this is a structural boundary of static-scan-based handles codegen, not a bug. See D-resolver-scope.`
+				: 'the single-resource GET route\'s handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.';
+			notes.push(`${entity.className}: ${note}`);
 		} else if (!handlerFile) {
 			notes.push(`${entity.className}: could not resolve ${fetchRoute.method}'s own defining file (import, or one barrel hop, from ${path.relative(repoRoot, fetchRoute.file)}) -- resolver NOT generated.`);
 		} else if (!selectFields) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.4.0",
+  "version": "1.5.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

package/scanners/adapters/java-spring.mjs

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { lineNumberAt, listRgFiles, byShallowestThenName, binaryAvailable } from '../text-util.mjs';
-import { maskNonCode, findClassOrRecordDeclaration, findClassLevelMappingArgs, findMappingAnnotations } from './_java-spring-analyzer.mjs';
+import { maskNonCode, findClassOrRecordDeclaration, findClassLevelMappingArgs, findMappingAnnotations, matchBalanced, findInterfaceExtendsDeclaration, splitTopLevelTypeArgs } from './_java-spring-analyzer.mjs';
 
 const JAVA_BUILD_FILE_GLOBS = ['build.gradle', 'build.gradle.kts', 'pom.xml'];
 
@@ -36,6 +36,23 @@ export function detectJavaSpringRoot(repoRoot) {
 	return null;
 }
 
+// D-spring-data-rest-adapter: literal substring grep, the same shape as
+// handles/providers/java-spring/emit.mjs's hasSpringAopDependency() -- but here, at SCAN time, for
+// a different reason: @Entity/@RestController pair with spring-boot-starter-data-jpa/-web,
+// dependencies virtually every real Spring Boot app already has, so this adapter has never needed
+// to cross-check a dependency before trusting an annotation. @RepositoryRestResource is unusually
+// easy to add decoratively (copied from a tutorial) without the actual
+// spring-boot-starter-data-rest starter, and without it ALL 6 synthesized routes would be
+// fictional, not just one field -- severe enough to warrant a check no other annotation in this
+// adapter needs. Same version-drift fragility hasSpringAopDependency's own history found for a
+// different artifact name (D-handles-pilot-cohort) is inherited here, not re-solved.
+export function hasSpringDataRestDependency(repoRoot) {
+	for (const buildFile of listRgFiles(repoRoot, JAVA_BUILD_FILE_GLOBS)) {
+		if (fs.readFileSync(buildFile, 'utf8').includes('spring-boot-starter-data-rest')) return true;
+	}
+	return false;
+}
+
 // O6: `rg --files` (no `--sort`) is explicitly unordered/parallel by ripgrep's own docs -- two
 // runs against an unchanged repo can return files in a different order, which without this sort
 // would propagate into non-deterministic controller/entity/module array order in every scan
@@ -165,6 +182,128 @@ function extractController(text, filePath) {
 	return { className, basePath, operationIds, endpoints, file: filePath, line: classLine };
 }
 
+const SPRING_DATA_REPOSITORY_SUPERTYPES = new Set(['JpaRepository', 'CrudRepository', 'PagingAndSortingRepository']);
+
+// D-spring-data-rest-adapter: Spring Data REST auto-generates a full CRUD REST API from a
+// repository interface annotated @RepositoryRestResource -- a real, common pattern extractController()
+// above is blind to (it only ever recognizes @RestController classes, and interface declarations
+// aren't recognized anywhere else in this file either). Mirrors extractController()'s shape/style,
+// but gated on a completely different annotation and declaration keyword. Populates
+// controller.declarations[]/endpoint.declarationIndex (see D-route-expansion-provenance) -- this
+// is the first adapter to do so. Every skip below is a deliberate "don't guess" refusal, not a
+// missing feature -- see this item's own DECISIONS.md entry for the full rationale per case.
+function extractRepositoryResource(text, filePath, hasDataRestDependency) {
+	if (!/@RepositoryRestResource\b/.test(text)) return { controller: null, note: null };
+
+	const masked = maskNonCode(text);
+	const decl = findInterfaceExtendsDeclaration(masked);
+	if (!decl || !SPRING_DATA_REPOSITORY_SUPERTYPES.has(decl.superName)) {
+		return { controller: null, note: null };
+	}
+	const declLine = lineNumberAt(text, decl.index);
+
+	if (!hasDataRestDependency) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource found on ${decl.name}, but no spring-boot-starter-data-rest dependency was found in this repo's build.gradle/build.gradle.kts/pom.xml -- Spring Data REST would not actually be active, so no routes are synthesized for this repository.`,
+		};
+	}
+
+	if (decl.typeArgsStart == null || decl.typeArgsEnd == null) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource found on ${decl.name}, but its "extends ${decl.superName}<...>" generic type arguments could not be parsed -- the entity type is unknown, so no routes are synthesized.`,
+		};
+	}
+	const typeArgs = splitTopLevelTypeArgs(masked.slice(decl.typeArgsStart, decl.typeArgsEnd));
+	if (typeArgs.length < 2) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource found on ${decl.name}, but "extends ${decl.superName}<...>" does not declare both an entity and id type -- no routes are synthesized.`,
+		};
+	}
+	const entityName = typeArgs[0];
+
+	// The annotation's own argument text -- scoped so a positional bare-quote grab (like
+	// extractQuotedOrValue() elsewhere in this file) can't accidentally pick a DIFFERENT string
+	// attribute (@RepositoryRestResource also has e.g. collectionResourceRel) instead of `path`.
+	const annotationMatch = masked.match(/@RepositoryRestResource\s*\(/);
+	let explicitPath = null;
+	if (annotationMatch) {
+		const openParen = annotationMatch.index + annotationMatch[0].length - 1;
+		const closeParen = matchBalanced(masked, openParen, '(', ')');
+		if (closeParen !== -1) {
+			const argsText = text.slice(openParen + 1, closeParen);
+			const pathMatch = argsText.match(/path\s*=\s*"([^"]*)"/);
+			if (pathMatch) explicitPath = pathMatch[1];
+		}
+	}
+	if (!explicitPath) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: @RepositoryRestResource on ${decl.name} has no explicit path="..." attribute -- Spring's default (an English-pluralized entity name) is not guessed here. Add path="..." and re-scan.`,
+		};
+	}
+
+	// Any interface-body override of an inherited CRUD action (e.g. `@Override @RestResource(exported
+	// = false) void deleteById(...)`) changes which of the 6 standard routes are actually exposed --
+	// safely determining WHICH action(s) that affects is out of scope, so the whole repository is
+	// refused rather than risk a partially-wrong route set (a resolver pointing at something that
+	// 404s/405s in the real app is worse than no resolver at all).
+	const bodyOpenBrace = masked.indexOf('{', decl.index);
+	const bodyCloseBrace = bodyOpenBrace !== -1 ? matchBalanced(masked, bodyOpenBrace, '{', '}') : -1;
+	const bodyText = bodyOpenBrace !== -1 && bodyCloseBrace !== -1 ? masked.slice(bodyOpenBrace, bodyCloseBrace) : '';
+	if (/@RestResource\b/.test(bodyText)) {
+		return {
+			controller: null,
+			note: `${filePath}:${declLine}: ${decl.name} overrides at least one CRUD method with @RestResource(...) -- which specific action(s) that suppresses or renames can't be safely determined by static scanning, so no routes are synthesized for this repository at all (a partially-correct route set is worse than none).`,
+		};
+	}
+
+	const basePath = `/${explicitPath.replace(/^\/+|\/+$/g, '')}`;
+	const declarations = [{
+		rule: 'java-spring:repository-rest-resource-crud',
+		line: declLine,
+		label: `@RepositoryRestResource(path="${explicitPath}") on ${decl.name}`,
+	}];
+	// D-spring-data-rest-adapter (SR2): operationId is bskel's OWN synthesized, self-describing
+	// label -- not a verified claim about what a real springdoc-generated document would call the
+	// same operation (that was never measured). A real --openapi-file document using a different
+	// name for the same route degrades to the existing CONTRACT_OPENAPI_MISSING_OPERATION warning
+	// every other operationId mismatch already produces, not a new failure mode. The synthesized,
+	// truthy operationId is what lets handles/providers/java-spring/plan.mjs's findFetchOperation()
+	// find these routes at all -- that function needed zero code changes (see SR3).
+	const ROUTES = [
+		{ verb: 'GET', path: basePath, suffix: 'CollectionResource' },
+		{ verb: 'POST', path: basePath, suffix: 'CollectionResource' },
+		{ verb: 'GET', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+		{ verb: 'PUT', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+		{ verb: 'PATCH', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+		{ verb: 'DELETE', path: `${basePath}/{id}`, suffix: 'ItemResource' },
+	];
+	const endpoints = ROUTES.map((r) => ({
+		verb: r.verb,
+		path: r.path,
+		operationId: `${r.verb.toLowerCase()}${entityName}${r.suffix}`,
+		method: null,
+		line: declLine,
+		declarationIndex: 0,
+	}));
+
+	return {
+		controller: {
+			className: decl.name,
+			basePath,
+			operationIds: endpoints.map((e) => e.operationId),
+			endpoints,
+			declarations,
+			file: filePath,
+			line: declLine,
+		},
+		note: null,
+	};
+}
+
 // D-entity-id-field-inheritance: found live against a real corpus check (spring-projects/
 // spring-petclinic) -- `Owner extends Person extends BaseEntity`, and `@Id` lives on `BaseEntity`
 // (a `@MappedSuperclass`), the standard, textbook JPA pattern for sharing an id/audit-field base
@@ -344,6 +483,13 @@ export function scanJavaSpring(repoRoot) {
 		return modules.get(key);
 	};
 
+	// D-spring-data-rest-adapter (SR5): computed once per scan, not per file -- a repo-wide,
+	// multi-module-aware check (same discovery detectJavaSpringRoot() already uses), not the
+	// single-root-file-only shape handles/providers/java-spring/emit.mjs's own
+	// hasSpringAopDependency() has.
+	const hasDataRestDependency = hasSpringDataRestDependency(repoRoot);
+	const repositoryResourceNotes = [];
+
 	for (const file of files) {
 		const text = fileTexts.get(file);
 		const mod = moduleOf(file, srcRoot, basePackage);
@@ -356,6 +502,11 @@ export function scanJavaSpring(repoRoot) {
 			const entity = extractEntity(text, file, classIndex);
 			if (entity) moduleEntry(mod).entities.push(entity);
 		}
+		if (/@RepositoryRestResource\b/.test(text)) {
+			const { controller, note } = extractRepositoryResource(text, file, hasDataRestDependency);
+			if (controller) moduleEntry(mod).controllers.push(controller);
+			if (note) repositoryResourceNotes.push(note);
+		}
 		if (mod && file.includes(`${path.sep}domain${path.sep}`) && /public\s+enum\s+\w+/.test(text)) {
 			const en = extractDomainEnum(text, file);
 			if (en) moduleEntry(mod).enums.push(en);
@@ -370,7 +521,7 @@ export function scanJavaSpring(repoRoot) {
 	// drift, and every other manifest-shaped gate input in this codebase (stack's `applied_file:`)
 	// is repo-relative too.
 	const filesRead = files.map((f) => path.relative(repoRoot, f));
-	return { srcRoot, modules: [...modules.values()], pathPrefixSignals: detectGlobalPathPrefixSignals(repoRoot), filesRead };
+	return { srcRoot, modules: [...modules.values()], pathPrefixSignals: detectGlobalPathPrefixSignals(repoRoot), filesRead, repositoryResourceNotes };
 }
 
 // G1: adapter descriptor consumed by scanners/registry.mjs -- see D-adapter-registry in
@@ -397,7 +548,7 @@ export const adapter = {
 	detect: detectJavaSpringRoot,
 	scan(repoRoot, _detection) {
 		const result = scanJavaSpring(repoRoot);
-		return { modules: result.modules, pathPrefixSignals: result.pathPrefixSignals, filesRead: result.filesRead };
+		return { modules: result.modules, pathPrefixSignals: result.pathPrefixSignals, filesRead: result.filesRead, repositoryResourceNotes: result.repositoryResourceNotes };
 	},
 	// S2 (D-gate-precision, continued): reuses the EXACT same listJavaFiles() call scan() itself
 	// makes -- no separate file-walking logic -- so the `scan` gate's staleness token can re-derive

package/scanners/index.mjs

@@ -218,6 +218,10 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	const confidence = chosen.confidence;
 	const modules = result.modules;
 	const pathPrefixSignals = result.pathPrefixSignals ?? [];
+	// D-spring-data-rest-adapter (SR4): the first per-adapter diagnostic-message passthrough into
+	// unknowns[] -- optional (`?? []`) so an adapter that doesn't populate it degrades to "nothing
+	// to report" rather than throwing, the same discipline apiSurfaceSource/filesRead already use.
+	const repositoryResourceNotes = result.repositoryResourceNotes ?? [];
 	const apiSurfaceSource = result.apiSurfaceSource ?? DEFAULT_API_SURFACE_SOURCE;
 	// S2 (D-gate-precision, continued): the adapter's own real read-set, persisted so
 	// lib/gate-definitions.mjs's `scan` gate can hash it for a precise staleness token instead of
@@ -301,6 +305,12 @@ export function runScan({ repoRoot, terms, includeDb = false, dbSchema = null, a
 	if (dbSchema?.live) {
 		unknowns.push(...computeDbDrift(dbSchema.live.tables, relatedModules));
 	}
+	// D-spring-data-rest-adapter (SR4): each entry names a repository the adapter recognized
+	// (found @RepositoryRestResource) but refused to synthesize routes for, and why -- a
+	// deliberate "don't guess" boundary, never silent.
+	if (repositoryResourceNotes.length > 0) {
+		unknowns.push(...repositoryResourceNotes);
+	}
 	// A1 §7: this scan can't correct a global path prefix (only --openapi-file's real-document
 	// reconciliation can, see D-openapi-reconciliation) -- but it CAN tell a user who doesn't know
 	// that flag exists that the defect is likely present, before they ever emit a wrong contract.

package/schemas/feature-contract.schema.json

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "required": ["sbf_contract", "feature_id", "feature_uid", "source", "operations", "warnings", "completeness"],
   "properties": {
-    "sbf_contract": { "const": "8" },
+    "sbf_contract": { "const": "9" },
     "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
     "feature_uid": { "type": "string", "format": "uuid" },
     "source": {
@@ -104,6 +104,17 @@
             "type": "array",
             "items": { "type": "string" }
           },
+          "expansion": {
+            "description": "X2 (D-route-expansion-provenance): present only when this operation's scan endpoint was expanded from a multi-route declaration recognized by the scan adapter (e.g. a future Rails/Laravel-style resource declaration, or a Spring Data REST @RepositoryRestResource) -- omitted for every ordinary 1:1 declared endpoint. `rule` is a namespaced <adapter-id>:<rule-slug> naming the expansion pattern; `declarationLine` is the single source line of the declaration itself (not this operation's own route); `label` is an optional human-readable description, null when not worth composing one.",
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["rule", "declarationLine"],
+            "properties": {
+              "rule": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" },
+              "declarationLine": { "type": "integer", "minimum": 1 },
+              "label": { "type": ["string", "null"] }
+            }
+          },
           "sourceDescription": {
             "description": "A10: the operation's `description`, copied verbatim from a real source document. Present only when `contract emit --descriptions` (opt-in, unlike every other source-backed field in this schema) was passed AND the source document declared one for this exact operation AND it did not exceed the length cap.",
             "type": "string"