backend-skeleton 1.2.0 → 1.4.0

package/contracts/csv.mjs

@@ -0,0 +1,100 @@
+// D-contract-csv: a spreadsheet-shaped projection of a feature contract -- one row per operation,
+// opened by someone who will never read a JSON Schema. Pure module, no I/O, no gate awareness, no
+// process -- mirrors contracts/export.mjs's own contract (see that file's header comment) exactly,
+// so this file can be unit-tested with hand-built `contract` objects and nothing else.
+//
+// C1: a fixed 14-column header, always -- see C2 in DECISIONS.md for why a column is never
+// dropped just because every operation leaves it blank (a scan-only contract's `summary`/`tags`/
+// `security` columns ARE the finding "nobody stated these", not something to hide by omitting the
+// column). C3: `description` is deliberately NOT a column (measured average 2,442.7 bytes/op,
+// larger than every other copied field combined -- see D-openapi-description).
+export const CSV_COLUMNS = Object.freeze([
+	{ name: 'operation_id', extract: (op, operationId) => operationId },
+	{ name: 'verb', extract: (op) => op.verb },
+	{ name: 'path', extract: (op) => op.path },
+	{ name: 'path_params', extract: (op) => sortedKeys(op.pathParams?.properties).join(', ') },
+	{ name: 'path_params_unverified', extract: (op) => (op.pathParamsHeuristic ?? []).join(', ') },
+	{ name: 'body', extract: (op) => String(op.body) },
+	{ name: 'request_body_required', extract: (op) => (op.requestBodyRequired == null ? '' : String(op.requestBodyRequired)) },
+	{ name: 'request_body_fields', extract: (op) => sortedKeys(op.requestBodySchema?.properties).join(', ') },
+	{ name: 'response_fields', extract: (op) => sortedKeys(op.responseSchema?.properties).join(', ') },
+	{ name: 'error_fields', extract: (op) => sortedKeys(op.errorSchema?.properties).join(', ') },
+	{ name: 'provenance', extract: (op) => op.provenance },
+	{ name: 'summary', extract: (op) => op.sourceSummary ?? '' },
+	{ name: 'tags', extract: (op) => (op.sourceTags ?? []).join(', ') },
+	{ name: 'security', extract: (op) => extractSecurity(op.sourceSecurity) },
+]);
+
+function sortedKeys(properties) {
+	return properties ? Object.keys(properties).sort() : [];
+}
+
+// `security: []` is a genuine positive claim ("this operation declared no auth requirement") --
+// see schemas/feature-contract.schema.json's own sourceSecurity description. An ABSENT
+// sourceSecurity means the source document said nothing about security for this operation at all.
+// The two must render distinguishably, or a reviewer cannot tell "confirmed open" from "unknown".
+function extractSecurity(sourceSecurity) {
+	if (sourceSecurity == null) return '';
+	if (sourceSecurity.length === 0) return '(source-declared: none)';
+	const schemeNames = new Set();
+	for (const requirement of sourceSecurity) {
+		for (const scheme of Object.keys(requirement)) schemeNames.add(scheme);
+	}
+	return [...schemeNames].sort().join(', ');
+}
+
+// C4: RFC 4180, hand-rolled -- quote a field iff it contains a double quote, comma, CR, or LF;
+// an embedded double quote is escaped by doubling it. Deliberately does NOT quote a field that
+// needs none of this (the negative case is what catches an over-eager escaper in tests). No new
+// dependency: this is the entire rule CSV has needed since RFC 4180 (2005).
+export function escapeCsvField(value) {
+	const str = String(value);
+	if (/["\n\r,]/.test(str)) {
+		return `"${str.replaceAll('"', '""')}"`;
+	}
+	return str;
+}
+
+// C4: LF line terminator (not RFC 4180's CRLF) -- every other artifact this project writes is
+// LF, and these files get committed/diffed. No comment/provenance preamble: line 1 is always the
+// header row, because a leading `#`/comment line breaks `pandas.read_csv`/`csv.DictReader`/every
+// spreadsheet importer's default settings -- provenance goes to stderr/`--json`, never into the
+// file itself.
+export function toCsv(header, rows) {
+	const lines = [header, ...rows].map((row) => row.map(escapeCsvField).join(','));
+	return `${lines.join('\n')}\n`;
+}
+
+// C5: deliberately does NOT check gate state, does NOT read a scan report, does NOT look at
+// path-prefix signals -- this is a pure projection of an already-loaded `contract` object. The
+// caller (bin/bskel.mjs's cmdContractExportCsv) owns every refusal/warning decision; this
+// function only ever succeeds or reports "there's nothing to export" for a genuinely empty
+// contract.
+export function buildContractCsv({ contract }) {
+	const operationIds = Object.keys(contract.operations).sort((a, b) => a.localeCompare(b));
+	if (operationIds.length === 0) {
+		return { ok: false, error: 'contract has zero operations' };
+	}
+
+	const header = CSV_COLUMNS.map((c) => c.name);
+	const rows = operationIds.map((operationId) => {
+		const op = contract.operations[operationId];
+		return CSV_COLUMNS.map((c) => c.extract(op, operationId));
+	});
+
+	// C2: coverage is reported alongside the file, never inferred by a reader staring at blank
+	// cells wondering whether the tool is broken.
+	const columns = CSV_COLUMNS.map((c, i) => ({
+		name: c.name,
+		populatedRows: rows.filter((row) => row[i] !== '').length,
+	}));
+	const emptyColumns = columns.filter((c) => c.populatedRows === 0).map((c) => c.name);
+
+	return {
+		ok: true,
+		csv: toCsv(header, rows),
+		rowCount: rows.length,
+		columns,
+		emptyColumns,
+	};
+}

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

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

@@ -0,0 +1,215 @@
+package {{BASE_PACKAGE}}.global.rules;
+
+import {{JACKSON_PACKAGE}}.JsonNode;
+import {{BASE_PACKAGE}}.global.rules.RuleSetLoader.CrossRule;
+import {{BASE_PACKAGE}}.global.rules.RuleSetLoader.FieldRule;
+import {{BASE_PACKAGE}}.global.rules.RuleSetLoader.RuleOperation;
+import {{BASE_PACKAGE}}.global.rules.RuleSetLoader.TransitionRule;
+
+import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * D-business-rules (R3/R9): pure, static, non-Spring executor for one feature's compiled business
+ * rules. A DUMB executor by design -- every semantic decision (which assertions exist, whether an
+ * assertion may apply to a field's type, whether two fields are comparable, whether a transition's
+ * states are real) was already made in JS by {@code rules/compile.mjs} at {@code bskel rules check}
+ * time. This class never interprets a JSON Schema and never decides what is checkable; it only
+ * executes an already-simplified instruction set. That is the same boundary
+ * {@code ContractCheck}/{@code handles/observe-schema-projection.mjs} hold, and it is what lets the
+ * Java, Python, and TypeScript executors be guaranteed to agree.
+ *
+ * <p><b>Redaction invariant, inherited from {@code ContractCheck} and equally binding here:</b>
+ * {@link Violation#message()} MUST NEVER interpolate an observed payload value -- only the JSON
+ * Pointer, the rule id, and the rule's own declared bound. A bound is safe because it came from the
+ * contract or from {@code rules.yaml}, i.e. from the developer, never from a request. A real
+ * payload value must never leave this process, structurally rather than by convention.
+ *
+ * <p>Generated by backend-skeleton ({@code bskel rules emit}). Do not hand-edit -- change the
+ * source rule and regenerate.
+ */
+public final class RuleCheck {
+
+	private RuleCheck() {}
+
+	public record Violation(String ruleId, String pointer, String kind, String message) {}
+
+	/**
+	 * Runs every FIELD and CROSS rule for one operation against a request body. Transition rules are
+	 * deliberately NOT run here -- see {@link #checkTransitions} for why they need an argument this
+	 * method does not have.
+	 */
+	public static List<Violation> check(RuleOperation rules, JsonNode body) {
+		List<Violation> violations = new ArrayList<>();
+		if (rules == null || body == null || !body.isObject()) return violations;
+		for (FieldRule rule : rules.field()) checkField(rule, body, violations);
+		for (CrossRule rule : rules.cross()) checkCross(rule, body, violations);
+		return violations;
+	}
+
+	private static JsonNode at(JsonNode body, String pointer) {
+		// Compiled pointers are always a single top-level "/field" segment (rules/compile.mjs
+		// refuses anything deeper), so this is a lookup, not a JSON Pointer implementation.
+		JsonNode node = body.get(pointer.substring(1));
+		return (node == null || node.isNull() || node.isMissingNode()) ? null : node;
+	}
+
+	private static void checkField(FieldRule rule, JsonNode body, List<Violation> out) {
+		JsonNode value = at(body, rule.pointer());
+		// An absent optional field is not a violation -- requiredness is the contract's own
+		// statement, enforced by ContractCheck, deliberately not duplicated in this vocabulary.
+		if (value == null) return;
+		switch (rule.assertion()) {
+			case "minLength" -> {
+				if (value.isTextual() && value.asText().length() < rule.value().intValue()) {
+					out.add(violation(rule.id(), rule.pointer(), "minLength", "shorter than the required minimum length of " + rule.value().intValue()));
+				}
+			}
+			case "maxLength" -> {
+				if (value.isTextual() && value.asText().length() > rule.value().intValue()) {
+					out.add(violation(rule.id(), rule.pointer(), "maxLength", "longer than the permitted maximum length of " + rule.value().intValue()));
+				}
+			}
+			case "minimum" -> compareNumber(rule, value, out, (actual, bound) -> actual.compareTo(bound) < 0, "is below the permitted minimum of ");
+			case "maximum" -> compareNumber(rule, value, out, (actual, bound) -> actual.compareTo(bound) > 0, "is above the permitted maximum of ");
+			case "exclusiveMinimum" -> compareNumber(rule, value, out, (actual, bound) -> actual.compareTo(bound) <= 0, "must be strictly greater than ");
+			case "exclusiveMaximum" -> compareNumber(rule, value, out, (actual, bound) -> actual.compareTo(bound) >= 0, "must be strictly less than ");
+			case "multipleOf" -> {
+				if (value.isNumber() && rule.value().decimalValue().signum() != 0) {
+					BigDecimal remainder = value.decimalValue().remainder(rule.value().decimalValue());
+					if (remainder.signum() != 0) {
+						out.add(violation(rule.id(), rule.pointer(), "multipleOf", "is not an exact multiple of " + rule.value().decimalValue().toPlainString()));
+					}
+				}
+			}
+			case "enum" -> {
+				boolean matched = false;
+				for (JsonNode allowed : rule.enumValues()) {
+					if (allowed.equals(value)) { matched = true; break; }
+				}
+				if (!matched) out.add(violation(rule.id(), rule.pointer(), "enum", "is not one of the " + rule.enumValues().size() + " permitted values"));
+			}
+			// No default branch that passes silently: an assertion name this executor does not know
+			// can only mean the artifact was produced by a NEWER bskel than the code generated here.
+			// Reported, never ignored -- the same posture ContractCheck's `unsupported` takes.
+			default -> out.add(violation(rule.id(), rule.pointer(), "unsupported",
+				"rule assertion \"" + rule.assertion() + "\" is not understood by this generated checker -- re-run `bskel rules emit` to regenerate it"));
+		}
+	}
+
+	private interface NumberPredicate { boolean violates(BigDecimal actual, BigDecimal bound); }
+
+	private static void compareNumber(FieldRule rule, JsonNode value, List<Violation> out, NumberPredicate predicate, String messagePrefix) {
+		if (!value.isNumber()) return;
+		BigDecimal bound = rule.value().decimalValue();
+		if (predicate.violates(value.decimalValue(), bound)) {
+			out.add(violation(rule.id(), rule.pointer(), rule.assertion(), messagePrefix + bound.toPlainString()));
+		}
+	}
+
+	private static void checkCross(CrossRule rule, JsonNode body, List<Violation> out) {
+		List<String> pointers = rule.pointers();
+		String first = pointers.get(0);
+		JsonNode a = at(body, first);
+
+		if ("requiredIf".equals(rule.assertion())) {
+			if (a != null && at(body, pointers.get(1)) == null) {
+				out.add(violation(rule.id(), pointers.get(1), "requiredIf", "is required because " + first + " is present"));
+			}
+			return;
+		}
+		if ("mutuallyExclusive".equals(rule.assertion())) {
+			List<String> present = new ArrayList<>();
+			for (String pointer : pointers) if (at(body, pointer) != null) present.add(pointer);
+			if (present.size() > 1) {
+				out.add(violation(rule.id(), first, "mutuallyExclusive", "at most one of " + String.join(", ", pointers) + " may be present, got " + present.size()));
+			}
+			return;
+		}
+
+		JsonNode b = at(body, pointers.get(1));
+		// Either side absent means there is nothing to compare. Deliberately not a violation:
+		// requiredness is the contract's statement, and a cross-field rule that also implied
+		// requiredness would enforce something the developer never declared.
+		if (a == null || b == null) return;
+
+		int cmp;
+		if (a.isNumber() && b.isNumber()) {
+			cmp = a.decimalValue().compareTo(b.decimalValue());
+		} else if (a.isTextual() && b.isTextual()) {
+			cmp = a.asText().compareTo(b.asText());
+		} else {
+			// rules/compile.mjs proved these two pointers were mutually comparable against the
+			// contract's declared types, so reaching here means the real payload disagrees with the
+			// contract. Reported as its own kind rather than silently passing.
+			out.add(violation(rule.id(), first, "incomparable", "could not be compared with " + pointers.get(1) + " -- the payload types differ from the contract's declared types"));
+			return;
+		}
+
+		boolean violated = switch (rule.assertion()) {
+			case "lt" -> cmp >= 0;
+			case "lte" -> cmp > 0;
+			case "gt" -> cmp <= 0;
+			case "gte" -> cmp < 0;
+			case "eq" -> cmp != 0;
+			case "neq" -> cmp == 0;
+			default -> false;
+		};
+		if (violated) {
+			out.add(violation(rule.id(), first, rule.assertion(), "must be " + symbolFor(rule.assertion()) + " " + pointers.get(1)));
+		} else if (!List.of("lt", "lte", "gt", "gte", "eq", "neq").contains(rule.assertion())) {
+			out.add(violation(rule.id(), first, "unsupported",
+				"rule assertion \"" + rule.assertion() + "\" is not understood by this generated checker -- re-run `bskel rules emit` to regenerate it"));
+		}
+	}
+
+	private static String symbolFor(String assertion) {
+		return switch (assertion) {
+			case "lt" -> "<"; case "lte" -> "<="; case "gt" -> ">"; case "gte" -> ">=";
+			case "eq" -> "equal to"; case "neq" -> "different from"; default -> assertion;
+		};
+	}
+
+	/**
+	 * Runs TRANSITION rules. Separate from {@link #check} because a transition guard is inherently a
+	 * statement about a change, and a request body only carries the DESTINATION state -- the current
+	 * state lives in the application's own datastore, which this class has no access to and must
+	 * never acquire.
+	 *
+	 * <p>{@code currentStates} maps a rule's pointer (e.g. {@code "/status"}) to that resource's
+	 * CURRENT persisted value, supplied by the caller. This is the one place a human must wire
+	 * something -- the same honest boundary {@code ResourceResolver#patchField} draws.
+	 *
+	 * <p><b>Fail-closed:</b> a pointer with no entry in {@code currentStates} produces an
+	 * {@code unchecked} violation, never a silent pass. A transition guard that quietly does nothing
+	 * because nobody supplied the current state is exactly the "looks enforced, never fires" failure
+	 * this whole item refuses elsewhere (see {@code RULE_TRANSITION_NOT_ENUM} in
+	 * {@code rules/diagnostics.mjs}).
+	 */
+	public static List<Violation> checkTransitions(RuleOperation rules, JsonNode body, Map<String, String> currentStates) {
+		List<Violation> violations = new ArrayList<>();
+		if (rules == null || body == null || !body.isObject()) return violations;
+		for (TransitionRule rule : rules.transition()) {
+			JsonNode target = at(body, rule.pointer());
+			if (target == null || !target.isTextual()) continue; // not changing this field
+			if (currentStates == null || !currentStates.containsKey(rule.pointer())) {
+				violations.add(violation(rule.id(), rule.pointer(), "unchecked",
+					"a transition guard is declared but the current state was not supplied, so it could not be evaluated -- pass it via checkTransitions(..., currentStates)"));
+				continue;
+			}
+			String from = currentStates.get(rule.pointer());
+			String to = target.asText();
+			if (from == null || from.equals(to)) continue; // no transition is occurring
+			if (rule.from().contains(from) && rule.to().contains(to)) continue; // explicitly allowed
+			violations.add(violation(rule.id(), rule.pointer(), "transition",
+				"this state change is not permitted -- allowed transitions are from {" + String.join(", ", rule.from()) + "} to {" + String.join(", ", rule.to()) + "}"));
+		}
+		return violations;
+	}
+
+	private static Violation violation(String ruleId, String pointer, String kind, String message) {
+		return new Violation(ruleId, pointer, kind, message);
+	}
+}

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

@@ -0,0 +1,132 @@
+package {{BASE_PACKAGE}}.global.rules;
+
+import {{JACKSON_PACKAGE}}.JsonNode;
+import {{JACKSON_PACKAGE}}.ObjectMapper;
+import {{BASE_PACKAGE}}.global.rules.RuleSetLoader.RuleOperation;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.aspectj.lang.ProceedingJoinPoint;
+import org.aspectj.lang.annotation.Around;
+import org.aspectj.lang.annotation.Aspect;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Component;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.util.List;
+
+/**
+ * D-business-rules (R8/R9): the opt-in AUTOMATIC half of business-rule checking -- exists only for
+ * methods a human has chosen to mark with {@link EnforceRules}. Checks FIELD and CROSS rules only;
+ * see {@link EnforceRules}'s own javadoc for why TRANSITION rules are excluded from this automatic
+ * path.
+ *
+ * <p><b>The observe/enforce split is a RUNTIME property, read once per call from {@code
+ * bskel.rules.mode} (default {@code "observe"}):</b>
+ * <ul>
+ *   <li>{@code observe} (default): every violation is logged (see {@code bskel.rules.violations}
+ *       logger), the wrapped call always proceeds. The same "measure before you enforce" posture
+ *       {@code ContractObservationAspect} already established for contract shape checking -- see
+ *       DECISIONS.md's D-openapi-request-schema for why turning validation on in a brownfield app
+ *       is a real behavior change (a request that used to succeed can start failing), not a free
+ *       safety improvement.</li>
+ *   <li>{@code enforce}: a violation rejects the call with HTTP 400 BEFORE it reaches the wrapped
+ *       method -- {@code joinPoint.proceed()} is never called. The rejection message may name a
+ *       rule id, a JSON Pointer, and a rule's own declared bound; it NEVER contains an observed
+ *       request value -- the same redaction invariant {@link RuleCheck#Violation} carries.</li>
+ * </ul>
+ *
+ * <p><b>Fail-open on an INTERNAL error, fail-closed on a REAL violation.</b> If this aspect itself
+ * cannot compute violations (a malformed request body, a loader problem), that is logged and the
+ * wrapped call proceeds unaffected, in BOTH modes -- an unrelated bug in this aspect must never
+ * become an outage for every request through an enforced endpoint. Only an actual, successfully
+ * computed rule violation can reject a call, and only in enforce mode.
+ *
+ * <p>Generated by backend-skeleton ({@code bskel rules emit}). Requires {@code
+ * spring-boot-starter-aop} on the classpath -- see {@link EnforceRules}'s own javadoc.
+ */
+@Aspect
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class RuleEnforcementAspect {
+
+	private static final org.slf4j.Logger VIOLATIONS = org.slf4j.LoggerFactory.getLogger("bskel.rules.violations");
+
+	private final RuleSetLoader ruleSetLoader;
+	private final ObjectMapper objectMapper;
+
+	@Value("${bskel.rules.mode:observe}")
+	private String mode;
+
+	@Around("@annotation(enforceRules)")
+	public Object enforce(ProceedingJoinPoint joinPoint, EnforceRules enforceRules) throws Throwable {
+		String operationId = enforceRules.operationId();
+		RuleOperation rules = ruleSetLoader.forOperation(operationId);
+		if (rules.isEmpty()) {
+			// Nothing compiled for this operation -- most commonly a feature with no rules.yaml and
+			// a contract that projected nothing enforceable. Proceeds silently: an empty rule set is
+			// not a misconfiguration worth logging on every call.
+			return joinPoint.proceed();
+		}
+
+		List<RuleCheck.Violation> violations = safelyCheck(joinPoint, rules, operationId);
+		if (!violations.isEmpty()) {
+			logViolations(operationId, violations);
+			if ("enforce".equals(mode)) {
+				throw new ResponseStatusException(HttpStatus.BAD_REQUEST, summarize(operationId, violations));
+			}
+		}
+		return joinPoint.proceed();
+	}
+
+	private List<RuleCheck.Violation> safelyCheck(ProceedingJoinPoint joinPoint, RuleOperation rules, String operationId) {
+		try {
+			Object requestBody = findRequestBodyArg(joinPoint);
+			if (requestBody == null) return List.of();
+			JsonNode body = objectMapper.valueToTree(requestBody);
+			return RuleCheck.check(rules, body);
+		} catch (Exception e) {
+			log.warn("RuleEnforcementAspect: could not evaluate rules for operation \"{}\" -- the wrapped call proceeds unaffected", operationId, e);
+			return List.of();
+		}
+	}
+
+	/** Same technique ContractObservationAspect's own findRequestBodyArg uses: a real, unambiguous `@RequestBody` signal on the method, never guessed by position. */
+	private static Object findRequestBodyArg(ProceedingJoinPoint joinPoint) {
+		if (!(joinPoint.getSignature() instanceof org.aspectj.lang.reflect.MethodSignature sig)) return null;
+		Method method = sig.getMethod();
+		Annotation[][] paramAnnotations = method.getParameterAnnotations();
+		Object[] args = joinPoint.getArgs();
+		for (int i = 0; i < paramAnnotations.length && i < args.length; i++) {
+			for (Annotation a : paramAnnotations[i]) {
+				if (a instanceof RequestBody) return args[i];
+			}
+		}
+		return null;
+	}
+
+	private void logViolations(String operationId, List<RuleCheck.Violation> violations) {
+		try {
+			for (RuleCheck.Violation v : violations) {
+				VIOLATIONS.warn("operation={} rule={} pointer={} kind={} mode={} -- {}", operationId, v.ruleId(), v.pointer(), v.kind(), mode, v.message());
+			}
+		} catch (Exception e) {
+			log.warn("RuleEnforcementAspect: could not log violations for operation \"{}\"", operationId, e);
+		}
+	}
+
+	/** Builds the HTTP 400 message from rule id / pointer / bound-derived text only -- never an observed value, the same redaction invariant every Violation#message() already holds. */
+	private static String summarize(String operationId, List<RuleCheck.Violation> violations) {
+		StringBuilder sb = new StringBuilder("business rule violation(s) for ").append(operationId).append(": ");
+		for (int i = 0; i < violations.size(); i++) {
+			if (i > 0) sb.append("; ");
+			RuleCheck.Violation v = violations.get(i);
+			sb.append(v.pointer()).append(" (").append(v.ruleId()).append("): ").append(v.message());
+		}
+		return sb.toString();
+	}
+}