backend-skeleton 1.3.0 → 1.5.0

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

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

@@ -0,0 +1,138 @@
+package {{BASE_PACKAGE}}.global.rules;
+
+import {{JACKSON_PACKAGE}}.JsonNode;
+import {{JACKSON_PACKAGE}}.ObjectMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.core.io.Resource;
+import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
+import org.springframework.stereotype.Component;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * D-business-rules (R9): loads every {@code bskel/*.rules.json} classpath resource (one per feature
+ * {@code bskel rules emit} has been run against) at startup and merges them into one flat map keyed
+ * by operationId. Same reasoning as {@code ObserveSchemaLoader}: a deployed app has no access to
+ * {@code specs/} at runtime, so the compiled artifact travels as a classpath resource.
+ *
+ * <p>This class does NO interpretation. It deserializes an artifact whose every semantic decision
+ * was already made and verified in JS by {@code rules/compile.mjs} -- see {@code RuleCheck}'s own
+ * javadoc for that boundary.
+ *
+ * <p>Generated by backend-skeleton ({@code bskel rules emit}). Do not hand-edit -- change the
+ * source rule and regenerate.
+ */
+@Component
+@Slf4j
+public class RuleSetLoader {
+
+	/** {@code value} carries the declared bound for numeric/length assertions; {@code enumValues} is used only by the `enum` assertion. */
+	public record FieldRule(String id, String pointer, String assertion, JsonNode value, List<JsonNode> enumValues, String origin) {}
+
+	public record CrossRule(String id, List<String> pointers, String assertion, List<String> types, String origin) {}
+
+	public record TransitionRule(String id, String pointer, List<String> from, List<String> to, String origin) {}
+
+	public record RuleOperation(List<FieldRule> field, List<CrossRule> cross, List<TransitionRule> transition) {
+		public static final RuleOperation EMPTY = new RuleOperation(List.of(), List.of(), List.of());
+		public boolean isEmpty() { return field.isEmpty() && cross.isEmpty() && transition.isEmpty(); }
+	}
+
+	private final Map<String, RuleOperation> operationsById = new HashMap<>();
+	private final Map<String, String> contractRefByOperation = new HashMap<>();
+
+	public RuleSetLoader(ObjectMapper objectMapper) {
+		try {
+			Resource[] resources = new PathMatchingResourcePatternResolver().getResources("classpath*:bskel/*.rules.json");
+			for (Resource resource : resources) {
+				try (InputStream in = resource.getInputStream()) {
+					load(objectMapper.readTree(in));
+				} catch (IOException e) {
+					// One unreadable resource must not take down application startup -- the same
+					// posture ObserveSchemaLoader takes for its own resources.
+					log.warn("bskel: could not read rules resource {} -- its rules will not be enforced", resource.getFilename(), e);
+				}
+			}
+		} catch (IOException e) {
+			log.warn("bskel: could not scan for bskel/*.rules.json rule resources -- no business rules will be enforced", e);
+		}
+	}
+
+	private void load(JsonNode doc) {
+		String contractRef = doc.path("contract_ref").asText("");
+		JsonNode operations = doc.path("operations");
+		operations.fieldNames().forEachRemaining((operationId) -> {
+			JsonNode entry = operations.path(operationId);
+			operationsById.put(operationId, new RuleOperation(
+				fieldRules(entry.path("field")),
+				crossRules(entry.path("cross")),
+				transitionRules(entry.path("transition"))
+			));
+			contractRefByOperation.put(operationId, contractRef);
+		});
+	}
+
+	private static List<FieldRule> fieldRules(JsonNode array) {
+		List<FieldRule> rules = new ArrayList<>();
+		if (!array.isArray()) return rules;
+		for (JsonNode node : array) {
+			JsonNode value = node.path("value");
+			List<JsonNode> enumValues = new ArrayList<>();
+			if (value.isArray()) for (JsonNode item : value) enumValues.add(item);
+			rules.add(new FieldRule(
+				node.path("id").asText(), node.path("pointer").asText(), node.path("assert").asText(),
+				value, List.copyOf(enumValues), node.path("origin").asText()
+			));
+		}
+		return List.copyOf(rules);
+	}
+
+	private static List<CrossRule> crossRules(JsonNode array) {
+		List<CrossRule> rules = new ArrayList<>();
+		if (!array.isArray()) return rules;
+		for (JsonNode node : array) {
+			rules.add(new CrossRule(
+				node.path("id").asText(), texts(node.path("pointers")), node.path("assert").asText(),
+				texts(node.path("types")), node.path("origin").asText()
+			));
+		}
+		return List.copyOf(rules);
+	}
+
+	private static List<TransitionRule> transitionRules(JsonNode array) {
+		List<TransitionRule> rules = new ArrayList<>();
+		if (!array.isArray()) return rules;
+		for (JsonNode node : array) {
+			rules.add(new TransitionRule(
+				node.path("id").asText(), node.path("pointer").asText(),
+				texts(node.path("from")), texts(node.path("to")), node.path("origin").asText()
+			));
+		}
+		return List.copyOf(rules);
+	}
+
+	private static List<String> texts(JsonNode array) {
+		List<String> out = new ArrayList<>();
+		if (array.isArray()) for (JsonNode node : array) out.add(node.asText());
+		return List.copyOf(out);
+	}
+
+	/** Never null -- an operation with no rules returns {@link RuleOperation#EMPTY}. */
+	public RuleOperation forOperation(String operationId) {
+		return operationsById.getOrDefault(operationId, RuleOperation.EMPTY);
+	}
+
+	/** The sha256 of the contract these rules were compiled and verified against. */
+	public String contractRefFor(String operationId) {
+		return contractRefByOperation.getOrDefault(operationId, "");
+	}
+
+	public int operationCount() {
+		return operationsById.size();
+	}
+}

package/handles/providers/python-fastapi/rules.mjs

@@ -0,0 +1,133 @@
+// D-business-rules (R9): the emit-side half of compiled business rules for python-fastapi. Mirrors
+// handles/providers/java-spring/rules.mjs's own shape exactly -- rules, observe, and handles are
+// orthogonal capabilities that happen to share the same repo-wide "generated infra" pattern.
+//
+// This emitter is deliberately THIN. It renders three fixed infra modules and copies an
+// already-compiled artifact into `rules_schemas/` -- 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 { renderExprInfix, groupDerivedByResource } from '../../../rules/derived.mjs';
+import { snakeCase } 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` -- rule_set.py
+// discovers every `rules_schemas/*.rules.json` file at module-import time 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. None of the three
+// templates need any {{VAR}} substitution -- same reasoning observe's own INFRA_FILES give (no
+// {{PKG}}, this stays decoupled from handles/, cross-imports are relative `from . import ...`).
+const INFRA_FILES = [
+	{ template: '__init__.py.tmpl', target: '__init__.py' },
+	{ template: 'rule_check.py.tmpl', target: 'rule_check.py' },
+	{ template: 'rule_set.py.tmpl', target: 'rule_set.py' },
+	{ template: 'enforce_rules.py.tmpl', target: 'enforce_rules.py' },
+];
+
+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 module per resource, one function per derived field -- same "complete, never a
+// stub" posture java-spring's own renderDerivedClass() holds. All params are plain numbers: this
+// vocabulary's operator set (add/sub/mul/div) is numeric-only by construction.
+function renderDerivedModule(resource, rules, featureId) {
+	const functions = rules.map((rule) => {
+		const params = rule.params.map(snakeCase).join(', ');
+		const refName = (name) => snakeCase(name);
+		const formula = renderExprInfix(rule.expr, refName);
+		return `def compute_${snakeCase(rule.field)}(${params}):\n    """${rule.field} = ${formula} -- rule "${rule.id}"."""\n    return ${formula}`;
+	});
+	return `"""Generated by backend-skeleton (bskel rules emit) for feature ${featureId}.
+
+D-business-rules (R5): a complete, callable pure function per derived field -- never a stub.
+Nothing calls these; wire the call site yourself wherever a computed field on ${resource} should
+actually be set (e.g. before persisting).
+"""
+
+
+${functions.join('\n\n\n')}
+`;
+}
+
+/**
+ * `plan` is the already-computed python-fastapi resource plan (bin/bskel.mjs calls
+ * planPythonFastApi() before this) -- only plan.importRoot/plan.topPackage are used, matching
+ * observe.mjs's own tolerance-of-unused-fields pattern. `artifact` is 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 emitRulesPythonFastApi({ repoRoot, featureId, artifact, plan, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const rulesDir = path.join(plan.importRoot, plan.topPackage, 'rules');
+	// __init__.py.tmpl is shared verbatim with the handles/observe infra sets (an empty marker
+	// file) -- reuse the same template rather than duplicating a one-line file a third time.
+	const sharedInitTemplate = path.join(PROVIDER_ROOT, 'templates', '__init__.py.tmpl');
+
+	const infraUnits = INFRA_FILES.map((f) => ({
+		id: f.template,
+		templatePath: f.template === '__init__.py.tmpl' ? sharedInitTemplate : path.join(TEMPLATES_DIR, f.template),
+		targetAbs: path.join(rulesDir, f.target),
+		rendered: render(f.template === '__init__.py.tmpl' ? sharedInitTemplate : path.join(TEMPLATES_DIR, f.template), {}),
+	}));
+
+	// R5/Phase 3: one <resource>_rules.py per resource with a derived field, emitted the SAME
+	// unconditional way the *.rules.json spec resource below is. See java-spring's own
+	// groupDerivedByResource() comment for the named cross-feature-collision limitation.
+	const derivedGroups = groupDerivedByResource(artifact.derived ?? []);
+	const derivedUnits = derivedGroups.map(([resource, rules]) => ({
+		resource,
+		targetAbs: path.join(rulesDir, `${snakeCase(resource)}_rules.py`),
+		content: renderDerivedModule(resource, rules, featureId),
+	}));
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'python-fastapi', 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 -- byte-identical to the file `bskel rules check`
+	// already wrote and schema-validated, deliberately NOT re-serialized here, the same "exactly
+	// one representation of these rules" invariant java-spring's own emitter holds.
+	const content = `${JSON.stringify(artifact, null, '\t')}\n`;
+	const target = path.join(rulesDir, 'rules_schemas', `${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: decorate the real route handler with @enforce_rules(operation_id="<operationId>", body_param="<arg name>") to have them checked automatically on every call.`,
+			`defaults to OBSERVE (logs to the "bskel.rules.violations" logger, never rejects a request) -- set the BSKEL_RULES_MODE=enforce environment variable 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 @enforce_rules -- they need the resource's CURRENT state, which no decorator can supply generically. Call rule_check.check_transitions(rules, body, {"/status": current.status}) 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) => `${snakeCase(u.resource)}_rules.py`).join(', ')}: complete, callable 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.`] : []),
+		],
+	};
+}