backend-skeleton 1.3.0 → 1.5.0

package/bin/bskel.mjs

@@ -46,6 +46,13 @@ import {
 } from '../lib/cross-feature-collisions.mjs';
 import { STACKS as NEW_STACKS, ALL_STACK_PARAMS, stacksAccepting, reusableParamsFor } from '../new/index.mjs';
 import { recordPattern, listPatterns, getPattern, isMissingPatternTable, summarizePatternFrequency } from '../patterns/store.mjs';
+// D-business-rules. rules/compile.mjs is pure (no fs/git/exit); rules/store.mjs owns all disk I/O.
+import { compileRules, summarizeArtifact } from '../rules/compile.mjs';
+import { rulesSourcePath, loadRulesSource, loadRulesArtifact, saveRulesArtifact, starterRulesSource } from '../rules/store.mjs';
+import { PREDICATE_KINDS, explainRule } from '../rules/vocabulary.mjs';
+import { emitRulesJavaSpring } from '../handles/providers/java-spring/rules.mjs';
+import { emitRulesPythonFastApi } from '../handles/providers/python-fastapi/rules.mjs';
+import { emitRulesTypeScriptExpress } from '../handles/providers/typescript-express/rules.mjs';
 import {
 	requireSingleLineText, requireValidJavaPackageName, requireValidArtifactId,
 	requireValidPythonVersion, requireValidLicense, requireValidDatabase, requireSupportedJavaVersion,
@@ -107,6 +114,10 @@ function usage() {
   bskel dependency declare --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..." [--memo "..."]
   bskel dependency remove --feature <id> --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."
   bskel dependency list --feature <id> [--json]
+  bskel rules check --feature <id> [--init] [--json]
+  bskel rules list --feature <id> [--json]
+  bskel rules explain --feature <id> --rule <id> [--json]
+  bskel rules emit --feature <id> [--module <name>] [--check] [--diff] [--force --reason "..."] [--json]
   bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."] [--json]
   bskel catalog lint [<choice>] [--json]
   bskel handles plan --feature <id> [--module <name>] [--resource type1,type2] [--diff] [--ast]
@@ -2015,6 +2026,292 @@ function cmdDependencyList(args) {
 	process.exit(0);
 }
 
+// D-business-rules (R6): compiles specs/<id>/rules.yaml (optional) plus the feature's own contract
+// into specs/<id>/rules/<id>.rules.json, and establishes the `rules` gate.
+//
+// Gated on `contract` having PASSED, the same posture `contract export`/`handles emit` take and
+// deliberately not the ungated posture `contract validate` takes: every rule's pointer, scalar
+// type, and enum state is verified against the contract, so compiling against a contract nobody
+// has accepted yet would bake unaccepted facts into an artifact that later drives real codegen.
+//
+// Refuses rather than approximates (R6): an ERROR-severity diagnostic is an authored mistake with
+// a real fix, not a fact to be waived -- see rules/diagnostics.mjs's own header for why this
+// command has no `waive` sibling the way `contract` does.
+function cmdRulesCheck(args) {
+	const flags = parseCommand('rules check', args);
+	if (flags.help) { console.log(renderCommandHelp('rules check')); process.exit(0); }
+	setContext('rules check', flags);
+	const root = requireRepoRoot();
+	requirePreflightPassed(root);
+	const contractResult = requireNamedGate(root, 'contract', flags.feature);
+	if (contractResult.code !== EXIT.PASS) {
+		const hint = contractResult.status === 'awaiting_disposition'
+			? `resolve it first -- \`bskel contract waive --feature ${flags.feature} --code <CODE> (--subject "..."|--all) --reason "..."\`, or \`bskel gate force contract --feature ${flags.feature} --reason "..."\` if intentional.`
+			: `run \`bskel contract emit --feature ${flags.feature}\` first.`;
+		fail(contractResult.code, gateReasonForCode(contractResult.code), `blocked: \`contract\` gate for ${flags.feature} is ${contractResult.status} -- ${hint}`, {
+			next_actions: [{ command: `bskel contract emit --feature ${flags.feature}`, reason: 'the contract gate has not passed yet', mutating: true }],
+		});
+	}
+
+	const contract = loadContract(root, flags.feature);
+	const contractRef = sha256File(specPath(root, flags.feature, 'contracts', `${flags.feature}.schema.json`));
+
+	const sourcePath = rulesSourcePath(root, flags.feature);
+	if (flags.init) {
+		// Never overwrites: a starter file is a convenience for an empty slot, not a reset button.
+		if (fs.existsSync(sourcePath)) {
+			fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `--init refuses to overwrite an existing ${path.relative(root, sourcePath)} -- edit it directly, or delete it first if you really want a fresh starter.`);
+		}
+		fs.mkdirSync(path.dirname(sourcePath), { recursive: true });
+		writeFileAtomic(sourcePath, starterRulesSource(flags.feature));
+	}
+
+	let source;
+	try {
+		source = loadRulesSource(root, flags.feature);
+	} catch (err) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', err.message);
+	}
+
+	const { artifact, diagnostics, blocking } = compileRules({ contract, source, contractRef });
+	const errors = diagnostics.filter((d) => d.severity === 'error');
+	const warnings = diagnostics.filter((d) => d.severity === 'warn');
+
+	if (blocking) {
+		// Nothing is written on refusal -- the same "Nothing was written." posture
+		// explainMissingCapability() uses. A half-compiled artifact would be worse than none.
+		const detail = errors.map((e) => `  ${e.code}${e.subject ? ` (${e.subject})` : ''}: ${e.message}`).join('\n');
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `blocked: ${errors.length} rule error(s) in ${path.relative(root, sourcePath)} -- nothing was written.\n${detail}`, {
+			next_actions: [{ command: `bskel rules check --feature ${flags.feature}`, reason: 'fix the rule(s) above and re-run', mutating: true }],
+		});
+	}
+
+	saveRulesArtifact(root, flags.feature, artifact);
+	const summary = summarizeArtifact(artifact);
+	const gateState = passNamedGate(root, 'rules', flags.feature, {
+		rule_count: summary.field + summary.cross + summary.transition + summary.derived,
+		from_contract: summary.fromContract,
+		declared: summary.declared,
+		unsupported: summary.unsupported,
+	});
+
+	if (flags.json) {
+		// `gateState.gates.rules`, not the whole state object -- passNamedGate() returns the full
+		// state, and every other command's --json exposes just its own gate record (cmdScan,
+		// cmdScanDisposition, cmdScanCrossFeatureCheck all do exactly this).
+		console.log(JSON.stringify({ feature_id: flags.feature, summary, unsupported: artifact.unsupported, gate: gateState.gates.rules }, null, 2));
+	} else {
+		console.log(`rules -- feature ${flags.feature}`);
+		console.log(`  ${summary.field} field, ${summary.cross} cross-field, ${summary.transition} transition across ${summary.operations} operation(s), ${summary.derived} derived (resource-scoped)`);
+		console.log(`  ${summary.fromContract} projected from the contract's own schema, ${summary.declared} declared in rules.yaml`);
+		if (warnings.length > 0) {
+			// Warnings go to stderr so `--json` stdout stays exactly one JSON document, and so
+			// --quiet never suppresses them -- D-cli-contract's own rule.
+			console.error(`\n${warnings.length} constraint(s) in the contract are NOT enforced by these rules:`);
+			for (const w of warnings) console.error(`  ${w.code}: ${w.message}`);
+		}
+		if (summary.field + summary.cross + summary.transition + summary.derived === 0) {
+			console.log(`  (no rules yet -- run \`bskel rules check --feature ${flags.feature} --init\` for a starter rules.yaml, or point \`bskel contract emit\` at an OpenAPI document to pick up its constraints automatically)`);
+		}
+	}
+	process.exit(0);
+}
+
+function cmdRulesList(args) {
+	const flags = parseCommand('rules list', args);
+	if (flags.help) { console.log(renderCommandHelp('rules list')); process.exit(0); }
+	setContext('rules list', flags);
+	const root = requireRepoRoot();
+	const artifact = loadRulesArtifactOrExit(root, flags.feature);
+
+	if (flags.json) { console.log(JSON.stringify(artifact, null, 2)); process.exit(0); }
+
+	console.log(`rules -- feature ${artifact.feature_id}`);
+	for (const [operationId, kinds] of Object.entries(artifact.operations)) {
+		console.log(`\n  ${operationId}`);
+		for (const r of kinds.field ?? []) console.log(`    [field]      ${r.id}  ${r.pointer} ${r.assert} ${JSON.stringify(r.value)}  (${r.origin})`);
+		for (const r of kinds.cross ?? []) console.log(`    [cross]      ${r.id}  ${r.pointers.join(` ${r.assert} `)}  (${r.origin})`);
+		for (const r of kinds.transition ?? []) console.log(`    [transition] ${r.id}  ${r.pointer}: ${r.from.join('|')} -> ${r.to.join('|')}  (${r.origin})`);
+	}
+	if (Object.keys(artifact.operations).length === 0 && (artifact.derived ?? []).length === 0) console.log('  (none)');
+	if ((artifact.derived ?? []).length > 0) {
+		console.log('\n  derived (resource-scoped, not operation-scoped):');
+		for (const r of artifact.derived) console.log(`    [derived]    ${r.id}  ${r.resource}.${r.field} <- (${r.params.join(', ')})  (${r.origin})`);
+	}
+	if (artifact.unsupported.length > 0) {
+		console.log(`\n  NOT enforced (${artifact.unsupported.length}):`);
+		for (const u of artifact.unsupported) console.log(`    ${u.code}: ${u.reason}`);
+	}
+	process.exit(0);
+}
+
+function cmdRulesExplain(args) {
+	const flags = parseCommand('rules explain', args);
+	if (flags.help) { console.log(renderCommandHelp('rules explain')); process.exit(0); }
+	setContext('rules explain', flags);
+	const root = requireRepoRoot();
+	const artifact = loadRulesArtifactOrExit(root, flags.feature);
+
+	const found = [];
+	for (const [operationId, kinds] of Object.entries(artifact.operations)) {
+		for (const kind of PREDICATE_KINDS) {
+			for (const rule of kinds[kind] ?? []) {
+				if (rule.id === flags.rule) found.push({ operation: operationId, kind, rule });
+			}
+		}
+	}
+	// `derived` rules are resource-scoped, not operation-scoped (R5) -- searched separately, same
+	// reasoning compileRules() gives for compiling them on their own path.
+	for (const rule of artifact.derived ?? []) {
+		if (rule.id === flags.rule) found.push({ operation: null, kind: 'derived', rule });
+	}
+	if (found.length === 0) {
+		const known = [];
+		for (const kinds of Object.values(artifact.operations)) {
+			for (const kind of PREDICATE_KINDS) for (const r of kinds[kind] ?? []) known.push(r.id);
+		}
+		for (const r of artifact.derived ?? []) known.push(r.id);
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', `no rule "${flags.rule}" in feature ${flags.feature} -- known rule ids: ${known.sort().join(', ') || '(none)'}`);
+	}
+	const [{ operation, kind, rule }] = found;
+	const explanation = explainRule({ operation, kind, rule });
+	if (flags.json) console.log(JSON.stringify({ feature_id: artifact.feature_id, operation, kind, rule, explanation }, null, 2));
+	else {
+		console.log(`rule "${rule.id}" -- feature ${artifact.feature_id}`);
+		if (operation) console.log(`  operation: ${operation}`);
+		else console.log(`  resource:  ${rule.resource}.${rule.field}`);
+		console.log(`  kind:      ${kind}`);
+		console.log(`  origin:    ${rule.origin}${rule.origin === 'contract' ? " (projected from this operation's own requestBodySchema -- change the OpenAPI document, not rules.yaml)" : ' (declared in rules.yaml)'}`);
+		console.log(`  means:     ${explanation}`);
+	}
+	process.exit(0);
+}
+
+// D-business-rules (R9): emits the generic rule executor plus the compiled artifact as a classpath
+// resource. Mirrors cmdObserveEmit's own precondition chain and blocked/--check reporting shape --
+// same emitUnits() conflict machinery, same --check/--diff/--force/--reason semantics, and the same
+// explicit adapter dispatch rather than handles/registry.mjs's plan+emit provider mechanism (this
+// command has no `plan` verb either, and operates directly on an already-compiled artifact).
+//
+// Gated on the `rules` gate rather than `contract`: the artifact this emits is what `rules check`
+// produced and schema-validated, so emitting while that gate is stale would ship a runtime resource
+// that no longer matches the rules anyone reviewed.
+function cmdRulesEmit(args) {
+	const flags = parseCommand('rules emit', args);
+	if (flags.help) { console.log(renderCommandHelp('rules emit')); process.exit(0); }
+	setContext('rules emit', flags);
+	const root = requireRepoRoot();
+	requirePreflightPassed(root);
+	if (flags.force && (!flags.reason || !flags.reason.trim())) {
+		fail(EXIT_CODES.BAD_ARGS, 'BAD_ARGS', 'bskel rules emit --force requires --reason "..." -- every overwrite of diverged generated code must be auditable');
+	}
+
+	const rulesResult = requireNamedGate(root, 'rules', flags.feature);
+	if (rulesResult.code !== EXIT.PASS) {
+		fail(rulesResult.code, gateReasonForCode(rulesResult.code), `blocked: \`rules\` gate for ${flags.feature} is ${rulesResult.status} -- run \`bskel rules check --feature ${flags.feature}\` first.`, {
+			next_actions: [{ command: `bskel rules check --feature ${flags.feature}`, reason: 'the rules gate has not passed yet', mutating: true }],
+		});
+	}
+
+	const scanReport = loadHydratedScanReportOrExit(root, flags.feature);
+	const artifact = loadRulesArtifactOrExit(root, flags.feature);
+	const dryRun = flags.check || flags.diff;
+
+	let result;
+	if (scanReport.adapter === 'java-spring') {
+		let basePackage;
+		try {
+			basePackage = detectBasePackage(root);
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		if (!basePackage) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', 'could not detect the base package (no *Application.java found under src/main/java) -- is this a Spring Boot project?');
+		}
+		try {
+			result = emitRulesJavaSpring({ repoRoot: root, featureId: flags.feature, artifact, basePackage, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+	} else if (scanReport.adapter === 'python-fastapi') {
+		// python's own package-root detection needs a module to anchor itself -- same asymmetry
+		// observe emit's own comment already documents for this exact adapter.
+		let fastApiPlan;
+		try {
+			fastApiPlan = planPythonFastApi({ repoRoot: root, scanReport, module: flags.module, resourceFilter: null });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		try {
+			result = emitRulesPythonFastApi({ repoRoot: root, featureId: flags.feature, artifact, plan: fastApiPlan, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+	} else if (scanReport.adapter === 'typescript-express') {
+		// TS's own project-root detection needs a module to anchor itself too -- same --module
+		// dependency python-fastapi's own rules emit already established.
+		let tsPlan;
+		try {
+			tsPlan = planTypeScriptExpress({ repoRoot: root, scanReport, module: flags.module, resourceFilter: null });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+		try {
+			result = emitRulesTypeScriptExpress({ repoRoot: root, featureId: flags.feature, artifact, plan: tsPlan, force: flags.force, reason: flags.reason, dryRun, computeDiff: flags.diff });
+		} catch (err) {
+			fail(EXIT_CODES.NOT_PASSED, 'PLAN_FAILED', err.message);
+		}
+	} else {
+		fail(EXIT_CODES.MISSING_CAPABILITY, 'MISSING_CAPABILITY', `bskel rules emit does not support the "${scanReport.adapter}" adapter yet (supported: java-spring, python-fastapi, typescript-express).`);
+	}
+
+	const { written, conflicts, orphans, notes, forced, blocked, actions, postEmitNotes = [] } = result;
+	const wouldChange = actions.some((a) => a.action !== 'unchanged' && a.action !== 'adopt-unchanged');
+	const allNotes = [...notes];
+	if (flags.force && forced.length === 0 && conflicts.length === 0) allNotes.push('--force had no effect: 0 conflicts found in this run\'s scope');
+	else if (flags.force && forced.length > 0) allNotes.push(`--force overwrote ${forced.length} diverged file(s): ${forced.join(', ')}`);
+
+	if (blocked) {
+		if (flags.json) {
+			console.log(JSON.stringify({ written, conflicts, orphans, forced, notes: allNotes, actions, blocked: true, check: dryRun }, null, 2));
+		} else {
+			const verb = dryRun ? 'would be blocked' : 'blocked';
+			console.error(`${verb}: ${conflicts.length} generated file(s) diverged from what backend-skeleton last wrote -- ${dryRun ? 'a real run would refuse to overwrite them' : 'refusing to overwrite'} without --force:`);
+			for (const c of conflicts) console.error(`  ${c.path} (${c.kind})\n    ${c.reason}`);
+			if (!dryRun) console.error(`\nre-run with: bskel rules emit --feature ${flags.feature}${flags.module ? ` --module ${flags.module}` : ''} --force --reason "..."`);
+		}
+		process.exit(EXIT_CODES.HANDLES_CONFLICT);
+	}
+
+	if (flags.json) {
+		console.log(JSON.stringify({ written, conflicts, orphans, forced, notes: allNotes, actions, blocked: false, check: dryRun, postEmitNotes }, null, 2));
+	} else if (!flags.quiet) {
+		console.log(`${dryRun ? 'would write' : 'wrote'} ${written.length} file(s):`);
+		for (const w of written) console.log(`  ${w}`);
+		if (allNotes.length > 0) {
+			console.log('\nnotes:');
+			for (const n of allNotes) console.log(`  - ${n}`);
+		}
+		if (dryRun) console.log(`\n${renderFileActions(actions)}`);
+		else for (const n of postEmitNotes) console.log(`\n${n}`);
+	}
+	if (dryRun) process.exit(wouldChange ? EXIT_CODES.CHECK_FAILED : EXIT_CODES.OK);
+	process.exit(0);
+}
+
+function loadRulesArtifactOrExit(root, featureId) {
+	let artifact;
+	try {
+		artifact = loadRulesArtifact(root, featureId);
+	} catch (err) {
+		fail(EXIT_CODES.NOT_PASSED, 'INVALID_ARTIFACT', err.message);
+	}
+	if (!artifact) {
+		fail(EXIT_CODES.NOT_PASSED, 'MISSING_ARTIFACT', `no compiled rules for ${featureId} -- run \`bskel rules check --feature ${featureId}\` first`);
+	}
+	return artifact;
+}
+
 // D-contract-history: a derived VIEW over the contract file's own git history in whatever repo
 // bskel is invoked in -- reads, never writes. Deliberately does NOT try to correlate a commit to
 // a specific `.sbf/<feature>.history.jsonl` gate-pass event: that file is per-machine, gitignored,
@@ -4156,6 +4453,17 @@ async function dispatchCommand(cmd, rest) {
 			process.exit(14);
 			break;
 		}
+		case 'rules': {
+			const sub = rest[0];
+			const subArgs = rest.slice(1);
+			if (sub === 'check') return cmdRulesCheck(subArgs);
+			if (sub === 'list') return cmdRulesList(subArgs);
+			if (sub === 'explain') return cmdRulesExplain(subArgs);
+			if (sub === 'emit') return cmdRulesEmit(subArgs);
+			usage();
+			process.exit(14);
+			break;
+		}
 		case 'stack': {
 			if (rest[0] === 'apply') return cmdStackApply(rest.slice(1));
 			usage();

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/java-spring/rules.mjs

@@ -0,0 +1,143 @@
+// D-business-rules (R9): the emit-side half of compiled business rules for java-spring. Its own
+// file, sibling to observe.mjs and emit.mjs, for exactly the reason observe.mjs's own header gives:
+// rules, observe, and handles are orthogonal capabilities that happen to share the same repo-wide
+// "generated infra" pattern, not the same feature.
+//
+// This emitter is deliberately THIN. It renders two fixed infra classes and copies an
+// already-compiled artifact onto the classpath -- it makes no decision about what a rule means.
+// Every such decision was made and verified in JS by rules/compile.mjs at `bskel rules check` time
+// (R3), which is the invariant that lets three languages agree.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitUnits, unifiedDiff } from '../../_engine.mjs';
+import { detectJacksonPackage } from './emit.mjs';
+import { renderExprInfix, groupDerivedByResource } from '../../../rules/derived.mjs';
+import { pascalCase } from '../../../rules/vocabulary.mjs';
+
+const PROVIDER_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.join(PROVIDER_ROOT, 'templates');
+
+// Repo-wide, shared across every feature that ever runs `bskel rules emit` -- RuleSetLoader
+// discovers every `bskel/*.rules.json` classpath resource at startup rather than being regenerated
+// per feature, so these files are true infra (create-once-per-repo, all-or-nothing conflict unit),
+// the same treatment observe.mjs's own INFRA_FILES get. EnforceRules/RuleEnforcementAspect (R8) are
+// the automatic field/cross wiring path -- transition rules stay a manual RuleCheck.checkTransitions
+// call, since a transition guard needs the resource's current state, which no annotation can supply
+// generically (see EnforceRules.java.tmpl's own javadoc).
+const INFRA_FILES = [
+	{ template: 'RuleSetLoader.java.tmpl', target: 'global/rules/RuleSetLoader.java' },
+	{ template: 'RuleCheck.java.tmpl', target: 'global/rules/RuleCheck.java' },
+	{ template: 'EnforceRules.java.tmpl', target: 'global/rules/EnforceRules.java' },
+	{ template: 'RuleEnforcementAspect.java.tmpl', target: 'global/rules/RuleEnforcementAspect.java' },
+];
+
+function render(templatePath, vars) {
+	let content = fs.readFileSync(templatePath, 'utf8');
+	for (const [key, value] of Object.entries(vars)) {
+		content = content.replaceAll(`{{${key}}}`, String(value));
+	}
+	return content;
+}
+
+function writeUnit(target, content) {
+	fs.mkdirSync(path.dirname(target), { recursive: true });
+	fs.writeFileSync(target, content);
+}
+
+// R5/Phase 3: one file per resource, one static method per derived field. A COMPLETE, compiling
+// pure function -- never a stub -- matching R5's own "the call site stays the human's, the
+// function itself does not" framing. Params are always `double`: this vocabulary's operator set
+// (add/sub/mul/div, R3) is numeric-only by construction, so there is no type to infer beyond
+// "a number" -- see rules/vocabulary.mjs's own DERIVED_OPS.
+function renderDerivedClass(resource, rules, featureId, basePackage) {
+	const methods = rules.map((rule) => {
+		const params = rule.params.map((p) => `double ${p}`).join(', ');
+		const formula = renderExprInfix(rule.expr);
+		return `\t/** {@code ${rule.field} = ${formula}} -- rule "${rule.id}". */\n\tpublic static double compute${pascalCase(rule.field)}(${params}) {\n\t\treturn ${formula};\n\t}`;
+	});
+	return `package ${basePackage}.global.rules;
+
+/**
+ * Generated by backend-skeleton ({@code bskel rules emit}) for feature ${featureId}.
+ *
+ * <p>D-business-rules (R5): a complete, compiling pure function per derived field -- never a
+ * stub. Nothing calls these methods; wire the call site yourself wherever a computed field on
+ * {@code ${resource}} should actually be set (e.g. before persisting).
+ */
+public final class ${resource}Rules {
+
+	private ${resource}Rules() {}
+
+${methods.join('\n\n')}
+}
+`;
+}
+
+/**
+ * @param {object} args
+ * @param {object} args.artifact the already-compiled, already-schema-validated rules artifact
+ *                               (rules/store.mjs's loadRulesArtifact) -- this function never reads
+ *                               specs/ itself, the same split observe.mjs holds for the contract.
+ */
+export function emitRulesJavaSpring({ repoRoot, featureId, artifact, basePackage, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const javaSrcRoot = path.join(repoRoot, 'src', 'main', 'java', ...basePackage.split('.'));
+	const jacksonPackage = detectJacksonPackage(repoRoot);
+
+	const infraUnits = INFRA_FILES.map((f) => ({
+		id: f.template,
+		templatePath: path.join(TEMPLATES_DIR, f.template),
+		targetAbs: path.join(javaSrcRoot, f.target),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage }),
+	}));
+
+	// R5/Phase 3: one <Resource>Rules.java per resource with a derived field, emitted the SAME
+	// unconditional way the .rules.json spec resource below is -- a complete, never-hand-edited
+	// pure function file, the same category as RuleCheck.java itself, not a resolver stub. See
+	// groupDerivedByResource()'s own doc comment for the named cross-feature-collision limitation.
+	const derivedGroups = groupDerivedByResource(artifact.derived ?? []);
+	const derivedUnits = derivedGroups.map(([resource, rules]) => ({
+		resource,
+		targetAbs: path.join(javaSrcRoot, 'global', 'rules', `${resource}Rules.java`),
+		content: renderDerivedClass(resource, rules, featureId, basePackage),
+	}));
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
+
+	for (const unit of derivedUnits) {
+		const relPath = path.relative(repoRoot, unit.targetAbs);
+		const diskContent = fs.existsSync(unit.targetAbs) ? fs.readFileSync(unit.targetAbs, 'utf8') : null;
+		const action = diskContent === null ? 'create' : (diskContent === unit.content ? 'unchanged' : 'update');
+		if (!dryRun) writeUnit(unit.targetAbs, unit.content);
+		result.written.push(relPath);
+		const actionEntry = { path: relPath, kind: 'derived', resourceType: unit.resource, action };
+		if (computeDiff && action === 'update') actionEntry.diff = unifiedDiff(relPath, diskContent, unit.content);
+		result.actions.push(actionEntry);
+	}
+
+	// The compiled artifact, copied verbatim onto the classpath. Byte-identical to the file
+	// `bskel rules check` already wrote and schema-validated -- deliberately NOT re-serialized
+	// here, so there is exactly one representation of these rules and no chance of the runtime
+	// executing something subtly different from what was audited. `kind: 'spec'` = always
+	// regenerated, not conflict-tracked (nobody hand-finishes a generated data file).
+	const content = `${JSON.stringify(artifact, null, '\t')}\n`;
+	const target = path.join(repoRoot, 'src', 'main', 'resources', 'bskel', `${featureId}.rules.json`);
+	const relPath = path.relative(repoRoot, target);
+	const diskContent = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+	const action = diskContent === null ? 'create' : (diskContent === content ? 'unchanged' : 'update');
+	if (!dryRun) writeUnit(target, content);
+	result.written.push(relPath);
+	const actionEntry = { path: relPath, kind: 'spec', action };
+	if (computeDiff && action === 'update') actionEntry.diff = unifiedDiff(relPath, diskContent, content);
+	result.actions.push(actionEntry);
+
+	return {
+		...result,
+		postEmitNotes: [
+			`field/cross rules are LOADED but not yet ACTIVE: add @EnforceRules(operationId = "<operationId>") to the real controller method to have them checked automatically on every call.`,
+			`defaults to OBSERVE (logs to the "bskel.rules.violations" logger, never rejects a request) -- set bskel.rules.mode: enforce in your own application.yml when you're ready for a real violation to reject with HTTP 400. No re-run of \`bskel rules emit\` needed to switch.`,
+			`transition rules are NOT checked by @EnforceRules -- they need the resource's CURRENT state, which no annotation can supply generically. Call RuleCheck.checkTransitions(rules, body, Map.of("/status", current.getStatus())) directly wherever your service layer has that state. A transition whose current state is not supplied reports "unchecked", never a silent pass.`,
+			...(derivedUnits.length > 0 ? [`derived field(s) compiled to ${derivedUnits.map((u) => `${u.resource}Rules`).join(', ')}: complete, compiling pure functions, but NOTHING calls them -- wire the call site yourself. If another feature also declares a derived field on the same resource, whichever feature's \`rules emit\` runs LAST wins for that file -- not merged.`] : []),
+		],
+	};
+}

package/handles/providers/java-spring/templates/EnforceRules.java.tmpl

@@ -0,0 +1,44 @@
+package {{BASE_PACKAGE}}.global.rules;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * D-business-rules (R8/R9): apply this to an EXISTING controller method (never generated onto
+ * one -- a human decides which methods are worth checking) to have {@link RuleEnforcementAspect}
+ * run this operation's compiled FIELD and CROSS rules against the real request body.
+ *
+ * <p><b>Does not check TRANSITION rules.</b> A transition guard needs the resource's CURRENT
+ * persisted state, which this annotation's own request-scoped context has no way to obtain
+ * generically -- that is the one honest gap this automatic path leaves open, matching
+ * {@link RuleCheck#checkTransitions}'s own javadoc. Call it directly, with the current state your
+ * own service layer already has, wherever a transition needs checking.
+ *
+ * <p>Whether a violation is logged only, or rejects the request, is a RUNTIME property
+ * ({@code bskel.rules.mode: observe|enforce}, default {@code observe}) -- not baked into the
+ * generated code, so switching from observation to enforcement never requires re-running
+ * {@code bskel rules emit}. See {@link RuleEnforcementAspect} for the full behavior.
+ *
+ * <p>Must be applied to the CONCRETE implementation method, not an interface method it overrides
+ * -- same {@code AopUtils#getMostSpecificMethod} constraint {@code ObserveContract}'s own javadoc
+ * already documents.
+ *
+ * <p>Example:
+ * <pre>{@code
+ * @EnforceRules(operationId = "updateWidget")
+ * public ResponseEntity<WidgetResponse> updateWidget(@PathVariable UUID widgetId, @RequestBody UpdateWidgetRequest request) { ... }
+ * }</pre>
+ *
+ * <p>Generated by backend-skeleton ({@code bskel rules emit}). Requires {@code
+ * spring-boot-starter-aop} on the target repo's own classpath -- NOT added automatically, matching
+ * this project's established boundary of never auto-editing a target's build file.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface EnforceRules {
+
+	/** Must match a key in the emitted {@code <feature-id>.rules.json}'s own operations map. */
+	String operationId();
+}