backend-skeleton 1.3.0 → 1.5.0

package/rules/store.mjs

@@ -0,0 +1,141 @@
+// D-business-rules (R1/R2): the I/O boundary for business rules. Paths, reading the hand-authored
+// YAML source, and reading/writing the compiled JSON artifact with schema validation on BOTH
+// sides -- the exact shape lib/cross-feature-collisions.mjs's
+// loadCrossFeatureResolution/saveCrossFeatureResolution and contracts/completeness.mjs's
+// loadResolution/saveResolution already hold ("refusing to write an invalid ...").
+//
+// rules/compile.mjs stays pure and filesystem-free; everything that touches disk lives here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { specPath } from '../lib/paths.mjs';
+import { readJsonIfExists, writeFileAtomic } from '../lib/fsutil.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
+import { RULES_SOURCE_SCHEMA } from './compile.mjs';
+
+// The hand-authored file. Sits directly in the feature's spec dir alongside dependencies.json --
+// both are human-authored declarations about this feature's own fields, so they are siblings.
+export function rulesSourcePath(root, featureId) {
+	return specPath(root, featureId, 'rules.yaml');
+}
+
+// The compiled artifact. In its own `rules/` subdirectory, matching how `handles/migration.sql`
+// already nests a generated artifact under the feature's spec dir.
+export function rulesArtifactPath(root, featureId) {
+	return specPath(root, featureId, 'rules', `${featureId}.rules.json`);
+}
+
+/**
+ * Reads and parses specs/<featureId>/rules.yaml. Returns null when the file does not exist at all
+ * -- a legal, common state meaning "this feature declares no hand-authored rules", which still
+ * compiles to a real artifact from contract-projected rules alone (R4).
+ *
+ * Throws on malformed YAML or a wrong/missing `schema` key. Deliberately NOT schema-validated
+ * beyond that: rules/compile.mjs resolves every rule against the contract itself and produces
+ * strictly better refusals (naming real known fields, real declared types, real enum states) than
+ * a structural schema could -- see schemas/feature-rules.schema.json's own description.
+ */
+export function loadRulesSource(root, featureId) {
+	const file = rulesSourcePath(root, featureId);
+	if (!fs.existsSync(file)) return null;
+	let parsed;
+	try {
+		parsed = parseYaml(fs.readFileSync(file, 'utf8'));
+	} catch (err) {
+		throw new Error(`${file}: not valid YAML -- ${err.message}`);
+	}
+	if (parsed === null || parsed === undefined) return { schema: RULES_SOURCE_SCHEMA, rules: [] };
+	if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+		throw new Error(`${file}: must be a YAML mapping with a "rules:" list, got ${Array.isArray(parsed) ? 'a list' : typeof parsed}`);
+	}
+	if (parsed.schema !== RULES_SOURCE_SCHEMA) {
+		throw new Error(`${file}: expected \`schema: ${RULES_SOURCE_SCHEMA}\` at the top of the file, got ${parsed.schema === undefined ? '(nothing)' : JSON.stringify(parsed.schema)}`);
+	}
+	if (parsed.rules !== undefined && !Array.isArray(parsed.rules)) {
+		throw new Error(`${file}: "rules" must be a list, got ${typeof parsed.rules}`);
+	}
+	return { schema: parsed.schema, rules: parsed.rules ?? [] };
+}
+
+export function loadRulesArtifact(root, featureId) {
+	const file = rulesArtifactPath(root, featureId);
+	const parsed = readJsonIfExists(file);
+	if (parsed === null) return null;
+	const { ok, errors } = validateAgainstSchema('feature-rules.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${file}: does not match schemas/feature-rules.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveRulesArtifact(root, featureId, artifact) {
+	const { ok, errors } = validateAgainstSchema('feature-rules.schema.json', artifact);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid rules artifact for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	const file = rulesArtifactPath(root, featureId);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	// Tab-indented + trailing newline, matching every other generated JSON artifact in this repo
+	// (observe's own <feature>.observed-schema.json uses exactly this). Byte-stable across runs so
+	// a no-op recompile leaves the file untouched and the `rules` gate stays green.
+	writeFileAtomic(file, `${JSON.stringify(artifact, null, '\t')}\n`);
+	return artifact;
+}
+
+// A starter rules.yaml, written only when the user explicitly asks for one and only when no file
+// exists. Deliberately contains ZERO real rules -- every example is commented out. Writing a live
+// rule here would be `bskel` inventing a constraint about the user's domain, exactly the line
+// D-greenfield-parameters draws ("does the generated file encode a claim about the user's domain
+// that the user did not state?").
+export function starterRulesSource(featureId) {
+	return `# Business rules for ${featureId}.
+#
+# Compiled by \`bskel rules check --feature ${featureId}\` into
+# specs/${featureId}/rules/${featureId}.rules.json, which is what the generated
+# runtime checkers actually execute. Nothing here is enforced until you run that command.
+#
+# Constraints your OpenAPI document already states (minLength, maximum, enum, ...) are picked up
+# AUTOMATICALLY from the contract -- you do not need to repeat them here. This file is only for
+# the rules no schema keyword can express.
+schema: ${RULES_SOURCE_SCHEMA}
+rules: []
+#
+# Uncomment and adapt any of these -- then run \`bskel rules check --feature ${featureId}\`, which
+# verifies every pointer, type, and enum state against your own contract before compiling.
+#
+#  - id: end-after-start
+#    kind: cross
+#    operation: createBooking
+#    pointers: [/startDate, /endDate]
+#    assert: lt
+#    reason: "a booking cannot end before it starts"
+#
+#  - id: publish-flow
+#    kind: transition
+#    operation: updateArticle
+#    pointer: /status
+#    from: [draft]
+#    to: [published, archived]
+#    reason: "an article may only be published or archived out of draft"
+#
+#  - id: discount-cap
+#    kind: field
+#    operation: createOrder
+#    pointer: /discountPercent
+#    assert: maximum
+#    value: 50
+#    reason: "policy cap, not expressible in the public API schema"
+#
+#  - id: order-total
+#    kind: derived
+#    resource: Order
+#    field: total
+#    expr:
+#      op: sub
+#      args:
+#        - op: mul
+#          args: [{ ref: price }, { ref: quantity }]
+#        - { ref: discount }
+#    reason: "total = price * quantity - discount; compiles to a real Order Rules pure function"
+`;
+}

package/rules/vocabulary.mjs

@@ -0,0 +1,172 @@
+// D-business-rules (R3): the closed vocabulary of business-rule assertions this project compiles
+// into target-language code. Frozen, small, and every member mechanically executable in Java,
+// Python, and TypeScript without interpretation -- that constraint is the whole design, not a
+// convenience. See DECISIONS.md's D-business-rules, R3.
+//
+// This module is PURE DATA plus pure predicates over it. It imports nothing, so it can be read by
+// the compiler, the CLI, and every provider emitter without any risk of the import cycle
+// D-zero-config-scan hit (adapter -> lib/doctor.mjs -> lib/verify.mjs -> scanners/registry.mjs).
+//
+// DELIBERATE NON-OVERLAP with `handles/observe-schema-projection.mjs`. That module already
+// projects `required`/`type`/`pattern` out of a contract's own requestBodySchema, and every
+// provider's generated checker already enforces those three. This vocabulary covers exactly the
+// constraints that projection DROPS -- so a single violation is never reported twice by two
+// different checkers, and neither module has to know what the other kept. `required` as an
+// unconditional assertion is therefore deliberately absent here: it is the contract's/OpenAPI
+// document's own statement, not a business rule layered on top. Its genuinely-new sibling,
+// `requiredIf` (conditional on another field), IS here, because no schema keyword expresses it.
+
+// ---- field assertions: one scalar JSON Pointer, one bounded comparison ----------------------
+//
+// `valueType` is what the rule's own `value` must be (validated at compile time, so a generated
+// runtime never has to defend against a malformed rule). `appliesTo` is the set of projected
+// scalar types the assertion is meaningful against -- checked against the contract's own
+// requestBodySchema at compile time (R6), which is how a rule that says "minLength on an integer"
+// is refused with the real type named instead of silently never firing.
+export const FIELD_ASSERTS = Object.freeze({
+	minLength:        Object.freeze({ valueType: 'integer', appliesTo: Object.freeze(['string']), summary: 'string length >= value' }),
+	maxLength:        Object.freeze({ valueType: 'integer', appliesTo: Object.freeze(['string']), summary: 'string length <= value' }),
+	minimum:          Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number >= value' }),
+	maximum:          Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number <= value' }),
+	exclusiveMinimum: Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number > value' }),
+	exclusiveMaximum: Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number < value' }),
+	multipleOf:       Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number is an exact multiple of value' }),
+	enum:             Object.freeze({ valueType: 'array',   appliesTo: Object.freeze(['string', 'number', 'integer', 'boolean']), summary: 'value is one of a fixed list' }),
+});
+
+// ---- cross-field assertions: two or more pointers, compared to each other -------------------
+//
+// `arity: 2` means exactly two pointers; `arity: 'n'` means two or more. `comparison: true` marks
+// the members whose operands must be mutually comparable (both numeric, or both string) -- a
+// `lt` between a string and an integer is refused at compile time rather than given some
+// language-specific coercion behavior that would differ across the three runtimes.
+export const CROSS_ASSERTS = Object.freeze({
+	lt:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first < second' }),
+	lte:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first <= second' }),
+	gt:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first > second' }),
+	gte:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first >= second' }),
+	eq:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first == second' }),
+	neq:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first != second' }),
+	requiredIf:        Object.freeze({ arity: 2,   comparison: false, summary: 'if the first is present, the second must be too' }),
+	mutuallyExclusive: Object.freeze({ arity: 'n', comparison: false, summary: 'at most one of these may be present' }),
+});
+
+// ---- the three predicate rule kinds -----------------------------------------------------------
+//
+// `derived` is deliberately NOT here: it produces a value rather than answering true/false about
+// one, so it cannot be executed by a predicate checker at all and takes a different compilation
+// path entirely (R5). Keeping the predicate kinds in their own frozen list is what lets the
+// compiler and every checker iterate them generically.
+export const PREDICATE_KINDS = Object.freeze(['field', 'cross', 'transition']);
+
+// Every kind an authored rule may declare -- PREDICATE_KINDS plus `derived`. Used only at the
+// "is this kind even real" dispatch point in rules/compile.mjs; every other consumer (the
+// checkers, `rules explain`'s search) still branches on PREDICATE_KINDS vs. `derived` separately,
+// because the two are executed through genuinely different mechanisms (R5).
+export const ALL_RULE_KINDS = Object.freeze([...PREDICATE_KINDS, 'derived']);
+
+// R5/Phase 3: the closed arithmetic vocabulary a `derived` rule's expr tree may use. Deliberately
+// tiny and binary-only (exactly 2 args per op) -- the explicit "no arbitrary arithmetic beyond the
+// frozen operator set" scope boundary this item's own plan named. A third operand is expressed by
+// nesting (`mul(mul(a,b),c)`), never by widening arity.
+export const DERIVED_OPS = Object.freeze(['add', 'sub', 'mul', 'div']);
+
+// PascalCase for Java/TypeScript method names (`computeTotal`), snake_case for Python
+// (`compute_total`) -- pure string transforms, reused by all three provider emitters so a
+// resource/field name is capitalized identically everywhere rather than three subtly different
+// regexes drifting apart.
+export function pascalCase(name) {
+	return String(name).replace(/(^\w|[-_]\w)/g, (m) => m.replace(/[-_]/, '').toUpperCase());
+}
+
+export function snakeCase(name) {
+	return String(name)
+		.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+		.replace(/[-\s]+/g, '_')
+		.toLowerCase();
+}
+
+// Where a compiled rule came from. `contract` = projected from the feature's own
+// requestBodySchema, i.e. a fact the user's OpenAPI document already asserts, transported (R4 --
+// the same "copying is not synthesizing" posture D-openapi-passthrough established). `declared` =
+// a human wrote it in rules.yaml. Kept distinct in the compiled artifact so an auditor can always
+// tell which constraints the document licensed and which a human added on top.
+export const RULE_ORIGINS = Object.freeze(['contract', 'declared']);
+
+// The scalar types a rule can address, matching observe-schema-projection.mjs's own SCALAR_TYPES
+// exactly -- a rule can only constrain something that module already projects as a scalar leaf.
+export const RULE_SCALAR_TYPES = Object.freeze(['string', 'number', 'integer', 'boolean']);
+
+export const FIELD_ASSERT_NAMES = Object.freeze(Object.keys(FIELD_ASSERTS).sort());
+export const CROSS_ASSERT_NAMES = Object.freeze(Object.keys(CROSS_ASSERTS).sort());
+
+export function getFieldAssert(name) {
+	return Object.hasOwn(FIELD_ASSERTS, name) ? FIELD_ASSERTS[name] : null;
+}
+
+export function getCrossAssert(name) {
+	return Object.hasOwn(CROSS_ASSERTS, name) ? CROSS_ASSERTS[name] : null;
+}
+
+// The typo-defense points, same shape as lib/gate-definitions.mjs's requireGateDefinition() and
+// contracts/completeness.mjs's requireWarningCode(): name the known values rather than letting a
+// misspelled assertion silently compile to a rule that can never fire.
+export function requireFieldAssert(name) {
+	const spec = getFieldAssert(name);
+	if (!spec) throw new Error(`unknown field assertion "${name}" -- known field assertions: ${FIELD_ASSERT_NAMES.join(', ')}`);
+	return spec;
+}
+
+export function requireCrossAssert(name) {
+	const spec = getCrossAssert(name);
+	if (!spec) throw new Error(`unknown cross-field assertion "${name}" -- known cross-field assertions: ${CROSS_ASSERT_NAMES.join(', ')}`);
+	return spec;
+}
+
+// Is `value` the right shape for this assertion's declared valueType? Deliberately strict:
+// `integer` rejects 1.5 AND rejects a numeric string, because a rule whose operand needs coercing
+// is a rule whose behavior would differ between Java, Python, and JS.
+export function valueMatchesType(valueType, value) {
+	switch (valueType) {
+		case 'integer': return typeof value === 'number' && Number.isInteger(value);
+		case 'number':  return typeof value === 'number' && Number.isFinite(value);
+		case 'array':   return Array.isArray(value) && value.length > 0;
+		case 'none':    return value === undefined;
+		default:        return false;
+	}
+}
+
+// Two projected scalar types are comparable if they are both numeric or both string. Booleans are
+// deliberately never comparable with `lt`/`gt` (ordering booleans is a language-specific accident,
+// not a business rule); `eq`/`neq` between two booleans is still refused here for the same reason
+// consistency matters more than convenience -- use a field `enum` assertion instead.
+export function typesAreComparable(a, b) {
+	const numeric = new Set(['number', 'integer']);
+	if (numeric.has(a) && numeric.has(b)) return true;
+	return a === 'string' && b === 'string';
+}
+
+// Renders one compiled rule as a plain-English sentence, for `bskel rules explain`. Pure and
+// exported (rather than built inline in the CLI) so it has a direct unit test, and so the same
+// wording can be reused by any future renderer -- the same call lib/workflow.mjs made when it
+// exported isMutatingCommand() instead of inlining it.
+export function explainRule({ kind, rule }) {
+	if (kind === 'field') {
+		const spec = getFieldAssert(rule.assert);
+		const what = spec ? spec.summary.replace('value', JSON.stringify(rule.value)) : `${rule.assert} ${JSON.stringify(rule.value)}`;
+		return `${rule.pointer} must satisfy: ${what}`;
+	}
+	if (kind === 'cross') {
+		const spec = getCrossAssert(rule.assert);
+		if (rule.assert === 'requiredIf') return `if ${rule.pointers[0]} is present, ${rule.pointers[1]} must be present too`;
+		if (rule.assert === 'mutuallyExclusive') return `at most one of ${rule.pointers.join(', ')} may be present`;
+		return `${rule.pointers[0]} must be ${spec ? spec.summary.replace('first ', '').replace(' second', '') : rule.assert} ${rule.pointers[1]}`;
+	}
+	if (kind === 'transition') {
+		return `${rule.pointer} may only change from {${rule.from.join(', ')}} to {${rule.to.join(', ')}}`;
+	}
+	if (kind === 'derived') {
+		return `${rule.resource}.${rule.field} is computed from (${rule.params.join(', ')}) -- see \`rules/derived.mjs\`'s renderExprInfix() for the exact formula, or the generated <Resource>Rules class itself`;
+	}
+	return `(no explanation available for kind "${kind}")`;
+}

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"