backend-skeleton 1.2.0 → 1.4.0

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.`] : []),
+		],
+	};
+}

package/handles/providers/python-fastapi/templates/enforce_rules.py.tmpl

@@ -0,0 +1,128 @@
+"""Generated by backend-skeleton (bskel rules emit). Do not hand-edit -- change the source rule
+and regenerate.
+
+D-business-rules (R8/R9): the opt-in AUTOMATIC half of business-rule checking -- exists only for a
+function a human has chosen to decorate with `@enforce_rules`. Checks FIELD and CROSS rules only;
+see this decorator's own parameter docs for why TRANSITION rules are excluded from this automatic
+path. Combines Java's separate `@EnforceRules` annotation + `RuleEnforcementAspect` interceptor
+into ONE decorator, deliberately -- same reasoning observe_contract.py's own docstring already
+gives: Python decorators natively ARE this ecosystem's method-interception mechanism.
+
+Only `operation_id` is required. `body_param` is the one deliberately EXPLICIT (never guessed, see
+D-resolver-scope in DECISIONS.md) parameter naming which of the wrapped function's own arguments is
+the request body -- default `None` means "skip checking, nothing to check without a body".
+
+The observe/enforce split is read from the `BSKEL_RULES_MODE` environment variable (default
+`"observe"`) on every call, not baked in at decoration time -- switching a deployed app from
+observation to enforcement is a config change, never a re-run of `bskel rules emit`. Same posture
+java-spring's own `bskel.rules.mode` Spring property takes.
+
+- `observe` (default): every violation is logged (the `bskel.rules.violations` logger), the
+  wrapped call always proceeds. The same "measure before you enforce" posture
+  `observe_contract`/`ContractObservationAspect` already establish for contract shape checking.
+- `enforce`: a violation raises `fastapi.HTTPException(400, ...)` BEFORE the wrapped function is
+  called. The 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 `rule_check.Violation` carries.
+
+Fail-open on an INTERNAL error, fail-closed on a REAL violation: if this decorator itself cannot
+compute violations (a malformed body, a loader problem), that is logged and the wrapped call
+proceeds unaffected, in BOTH modes.
+
+CRITICAL, python-specific correctness requirement (same as observe_contract.py's own note):
+detects whether the wrapped function is a coroutine function at DECORATION time and dispatches to
+a genuinely separate async/sync wrapper -- a single wrapper naively calling an async function
+without awaiting it would return an unawaited coroutine object as the "result".
+
+Example:
+    @enforce_rules(operation_id="updateWidget", body_param="request")
+    async def update_widget(widget_id: str, request: UpdateWidgetRequest):
+        ...
+"""
+import functools
+import inspect
+import logging
+import os
+
+from fastapi import HTTPException
+
+from . import rule_check
+from . import rule_set
+
+logger = logging.getLogger(__name__)
+_VIOLATIONS = logging.getLogger("bskel.rules.violations")
+
+
+def _mode() -> str:
+    return os.environ.get("BSKEL_RULES_MODE", "observe")
+
+
+def _to_jsonable(value):
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    return value
+
+
+def _safely_check(rules: dict, body_value, operation_id: str) -> list:
+    try:
+        if body_value is None:
+            return []
+        return rule_check.check(rules, _to_jsonable(body_value))
+    except Exception:
+        logger.warning('enforce_rules: could not evaluate rules for operation "%s" -- the wrapped call proceeds unaffected', operation_id, exc_info=True)
+        return []
+
+
+def _log_violations(operation_id: str, violations: list, mode: str) -> None:
+    try:
+        for v in violations:
+            _VIOLATIONS.warning("operation=%s rule=%s pointer=%s kind=%s mode=%s -- %s", operation_id, v.rule_id, v.pointer, v.kind, mode, v.message)
+    except Exception:
+        logger.warning('enforce_rules: could not log violations for operation "%s"', operation_id, exc_info=True)
+
+
+def _summarize(operation_id: str, violations: list) -> str:
+    """Built from rule id / pointer / bound-derived text only -- never an observed value, the same
+    redaction invariant every Violation.message already holds."""
+    parts = [f"{v.pointer} ({v.rule_id}): {v.message}" for v in violations]
+    return f"business rule violation(s) for {operation_id}: " + "; ".join(parts)
+
+
+def enforce_rules(*, operation_id: str, body_param: str | None = None):
+    def decorator(fn):
+        signature = inspect.signature(fn)
+
+        def _evaluate(bound: inspect.BoundArguments):
+            rules = rule_set.for_operation(operation_id)
+            if not rules["field"] and not rules["cross"]:
+                return []  # nothing compiled for this operation -- not worth logging on every call
+            body_value = bound.arguments.get(body_param) if body_param is not None else None
+            return _safely_check(rules, body_value, operation_id)
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def wrapper(*args, **kwargs):
+                bound = signature.bind(*args, **kwargs)
+                bound.apply_defaults()
+                violations = _evaluate(bound)
+                if violations:
+                    mode = _mode()
+                    _log_violations(operation_id, violations, mode)
+                    if mode == "enforce":
+                        raise HTTPException(status_code=400, detail=_summarize(operation_id, violations))
+                return await fn(*args, **kwargs)
+        else:
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                bound = signature.bind(*args, **kwargs)
+                bound.apply_defaults()
+                violations = _evaluate(bound)
+                if violations:
+                    mode = _mode()
+                    _log_violations(operation_id, violations, mode)
+                    if mode == "enforce":
+                        raise HTTPException(status_code=400, detail=_summarize(operation_id, violations))
+                return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

package/handles/providers/python-fastapi/templates/rule_check.py.tmpl

@@ -0,0 +1,178 @@
+"""Generated by backend-skeleton (bskel rules emit). Do not hand-edit -- change the source rule
+and regenerate.
+
+D-business-rules (R3/R9): pure, stdlib-only executor for one feature's compiled business rules.
+A DUMB executor by design -- every semantic decision (which assertions exist, whether one applies
+to a field's type, whether two fields are comparable, whether a transition's states are real) was
+already made in JS by rules/compile.mjs at `bskel rules check` time. Mirrors
+handles/providers/java-spring/templates/RuleCheck.java.tmpl exactly, field-for-field, so both
+runtimes are guaranteed to agree -- see that file's own docstring for the full "one interpreter"
+reasoning this project holds throughout.
+
+Redaction invariant, inherited from contract_check.py and equally binding here: `Violation.message`
+MUST NEVER interpolate an observed payload value -- only the JSON Pointer, the rule id, and the
+rule's own declared bound (safe because it came from the contract or from rules.yaml, i.e. from the
+developer, never from a request).
+"""
+from typing import NamedTuple
+
+
+class Violation(NamedTuple):
+    rule_id: str
+    pointer: str
+    kind: str
+    message: str
+
+
+def _at(body, pointer: str):
+    """Compiled pointers are always a single top-level "/field" segment (rules/compile.mjs
+    refuses anything deeper) -- this is a dict lookup, not a JSON Pointer implementation."""
+    if not isinstance(body, dict):
+        return None
+    return body.get(pointer[1:])
+
+
+_CROSS_SYMBOLS = {"lt": "<", "lte": "<=", "gt": ">", "gte": ">=", "eq": "equal to", "neq": "different from"}
+
+
+def check(rules: dict, body) -> list:
+    """Runs every FIELD and CROSS rule in `rules` (one operation's own entry from a loaded
+    *.rules.json) against a request body. TRANSITION rules are deliberately NOT run here -- see
+    check_transitions() for why they need an argument this function does not have."""
+    violations: list = []
+    if not isinstance(body, dict):
+        return violations
+    for rule in rules.get("field", []):
+        violations.extend(_check_field(rule, body))
+    for rule in rules.get("cross", []):
+        violations.extend(_check_cross(rule, body))
+    return violations
+
+
+def _check_field(rule: dict, body: dict) -> list:
+    value = _at(body, rule["pointer"])
+    if value is None:
+        # An absent optional field is not a violation -- requiredness is the contract's own
+        # statement, enforced by contract_check.py, deliberately not duplicated in this vocabulary.
+        return []
+    assertion = rule["assert"]
+    bound = rule.get("value")
+
+    if assertion == "minLength":
+        if isinstance(value, str) and len(value) < int(bound):
+            return [Violation(rule["id"], rule["pointer"], "minLength", f"shorter than the required minimum length of {int(bound)}")]
+        return []
+    if assertion == "maxLength":
+        if isinstance(value, str) and len(value) > int(bound):
+            return [Violation(rule["id"], rule["pointer"], "maxLength", f"longer than the permitted maximum length of {int(bound)}")]
+        return []
+    if assertion == "minimum":
+        return _compare_number(rule, value, bound, lambda a, b: a < b, "is below the permitted minimum of ")
+    if assertion == "maximum":
+        return _compare_number(rule, value, bound, lambda a, b: a > b, "is above the permitted maximum of ")
+    if assertion == "exclusiveMinimum":
+        return _compare_number(rule, value, bound, lambda a, b: a <= b, "must be strictly greater than ")
+    if assertion == "exclusiveMaximum":
+        return _compare_number(rule, value, bound, lambda a, b: a >= b, "must be strictly less than ")
+    if assertion == "multipleOf":
+        if isinstance(value, (int, float)) and not isinstance(value, bool) and bound:
+            remainder = value % bound
+            if min(abs(remainder), abs(remainder - bound)) > 1e-9:
+                return [Violation(rule["id"], rule["pointer"], "multipleOf", f"is not an exact multiple of {bound}")]
+        return []
+    if assertion == "enum":
+        if value not in (bound or []):
+            return [Violation(rule["id"], rule["pointer"], "enum", f"is not one of the {len(bound or [])} permitted values")]
+        return []
+    # No fallthrough 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 contract_check.py's own `unsupported` takes.
+    return [Violation(rule["id"], rule["pointer"], "unsupported", f'rule assertion "{assertion}" is not understood by this generated checker -- re-run `bskel rules emit` to regenerate it')]
+
+
+def _compare_number(rule: dict, value, bound, violates, message_prefix: str) -> list:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return []
+    if violates(value, bound):
+        return [Violation(rule["id"], rule["pointer"], rule["assert"], f"{message_prefix}{bound}")]
+    return []
+
+
+def _check_cross(rule: dict, body: dict) -> list:
+    pointers = rule["pointers"]
+    assertion = rule["assert"]
+    first = pointers[0]
+    a = _at(body, first)
+
+    if assertion == "requiredIf":
+        if a is not None and _at(body, pointers[1]) is None:
+            return [Violation(rule["id"], pointers[1], "requiredIf", f"is required because {first} is present")]
+        return []
+    if assertion == "mutuallyExclusive":
+        present = [p for p in pointers if _at(body, p) is not None]
+        if len(present) > 1:
+            return [Violation(rule["id"], first, "mutuallyExclusive", f"at most one of {', '.join(pointers)} may be present, got {len(present)}")]
+        return []
+
+    b = _at(body, pointers[1])
+    # Either side absent means there is nothing to compare -- see RuleCheck.java's own comment for
+    # why this is deliberately not a violation.
+    if a is None or b is None:
+        return []
+
+    if isinstance(a, bool) or isinstance(b, bool):
+        # 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 (a boolean where a number/string was declared).
+        return [Violation(rule["id"], first, "incomparable", f"could not be compared with {pointers[1]} -- the payload types differ from the contract's declared types")]
+    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
+        cmp = (a > b) - (a < b)
+    elif isinstance(a, str) and isinstance(b, str):
+        cmp = (a > b) - (a < b)
+    else:
+        return [Violation(rule["id"], first, "incomparable", f"could not be compared with {pointers[1]} -- the payload types differ from the contract's declared types")]
+
+    if assertion not in _CROSS_SYMBOLS:
+        return [Violation(rule["id"], first, "unsupported", f'rule assertion "{assertion}" is not understood by this generated checker -- re-run `bskel rules emit` to regenerate it')]
+
+    violated = {
+        "lt": cmp >= 0, "lte": cmp > 0, "gt": cmp <= 0, "gte": cmp < 0, "eq": cmp != 0, "neq": cmp == 0,
+    }[assertion]
+    if violated:
+        return [Violation(rule["id"], first, assertion, f"must be {_CROSS_SYMBOLS[assertion]} {pointers[1]}")]
+    return []
+
+
+def check_transitions(rules: dict, body, current_states: dict | None) -> list:
+    """Runs TRANSITION rules. Separate from 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 function has no access to and must
+    never acquire.
+
+    `current_states` maps a rule's pointer (e.g. "/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 resolver.py's own patch_field draws.
+
+    Fail-closed: a pointer with no entry in `current_states` produces an "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 RULE_TRANSITION_NOT_ENUM in rules/diagnostics.mjs).
+    """
+    violations: list = []
+    if not isinstance(body, dict):
+        return violations
+    for rule in rules.get("transition", []):
+        target = _at(body, rule["pointer"])
+        if target is None or not isinstance(target, str):
+            continue  # not changing this field
+        if current_states is None or rule["pointer"] not in current_states:
+            violations.append(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 check_transitions(..., current_states)"))
+            continue
+        from_state = current_states[rule["pointer"]]
+        to_state = target
+        if from_state is None or from_state == to_state:
+            continue  # no transition is occurring
+        if from_state in rule["from"] and to_state in rule["to"]:
+            continue  # explicitly allowed
+        violations.append(Violation(rule["id"], rule["pointer"], "transition", f"this state change is not permitted -- allowed transitions are from {{{', '.join(rule['from'])}}} to {{{', '.join(rule['to'])}}}"))
+    return violations

package/handles/providers/python-fastapi/templates/rule_set.py.tmpl

@@ -0,0 +1,59 @@
+"""Generated by backend-skeleton (bskel rules emit). Do not hand-edit -- change the source rule
+and regenerate.
+
+D-business-rules (R9): loads every `<feature-id>.rules.json` file under this package's own
+`rules_schemas/` directory (one per feature `bskel rules emit` has been run against) at MODULE
+IMPORT time and merges them into one flat dict keyed by operationId. Mirrors observed_schema.py's
+own shape exactly -- same "loaded once via Python's module cache" property, same plain-glob
+discovery (this ecosystem only ever runs from source, never an installed wheel -- see that
+module's own docstring for the full reasoning).
+
+This module does NO interpretation. It deserializes an artifact whose every semantic decision was
+already made and verified in JS by rules/compile.mjs -- see rule_check.py's own docstring for that
+boundary.
+"""
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_SCHEMAS_DIR = Path(__file__).parent / "rules_schemas"
+
+_EMPTY_OPERATION = {"field": [], "cross": [], "transition": []}
+
+
+def _load_one(path: Path) -> dict:
+    try:
+        raw = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        logger.warning("rule_set: could not read/parse %s -- its rules will not be enforced", path, exc_info=True)
+        return {}
+    operations = {}
+    for operation_id, entry in raw.get("operations", {}).items():
+        operations[operation_id] = {
+            "field": list(entry.get("field", [])),
+            "cross": list(entry.get("cross", [])),
+            "transition": list(entry.get("transition", [])),
+        }
+    return operations
+
+
+def _load_all() -> dict:
+    merged: dict = {}
+    if not _SCHEMAS_DIR.is_dir():
+        return merged
+    for path in sorted(_SCHEMAS_DIR.glob("*.rules.json")):
+        for operation_id, ops in _load_one(path).items():
+            if operation_id in merged:
+                logger.warning('rule_set: operationId "%s" is declared by more than one *.rules.json on disk -- the last one loaded wins', operation_id)
+            merged[operation_id] = ops
+    return merged
+
+
+_OPERATIONS = _load_all()
+
+
+def for_operation(operation_id: str) -> dict:
+    """Never None -- an operation with no rules returns the shared empty operation dict."""
+    return _OPERATIONS.get(operation_id, _EMPTY_OPERATION)