backend-skeleton 1.3.0 → 1.5.0

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)

package/handles/providers/typescript-express/plan.mjs

@@ -57,7 +57,13 @@ function findFetchRoute(controllers, entityClassName) {
 			if (ep.verb !== 'GET') continue;
 			const suffix = ep.path.slice(controller.basePath.length);
 			if (/^\/:[^/(]+(\([^)]*\))?$/.test(suffix)) {
-				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className };
+				// X5 (D-route-expansion-provenance): threaded through so the caller can distinguish
+				// "inline arrow handler" (this provider's real, current no-method case) from "1:N
+				// framework-synthesized route" (a declaration is present) in its note text. null on
+				// every endpoint in today's adapter (it never populates declarationIndex) --
+				// forward-compatible only, not yet reachable.
+				const declaration = ep.declarationIndex != null ? (controller.declarations?.[ep.declarationIndex] ?? null) : null;
+				return { method: ep.method, path: ep.path, file: controller.file, line: ep.line, controllerClassName: controller.className, declaration };
 			}
 		}
 	}
@@ -183,7 +189,14 @@ export function plan({ repoRoot, scanReport, module: moduleName, resourceFilter
 		if (!fetchRoute) {
 			notes.push(`${entity.className}: no single-resource GET route found on a router whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
 		} else if (!fetchRoute.method) {
-			notes.push(`${entity.className}: the single-resource GET route's handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.`);
+			// X5 (D-route-expansion-provenance): a declaration means this route was expanded from a
+			// 1:N framework construct (no literal per-action method exists at all, not yet reachable
+			// in this adapter); no declaration keeps this provider's own real, current cause (an
+			// inline arrow-function handler) unchanged.
+			const note = fetchRoute.declaration
+				? `the matched endpoint (GET ${fetchRoute.path}) was expanded from ${fetchRoute.declaration.label ?? fetchRoute.declaration.rule} at ${path.relative(repoRoot, fetchRoute.file)}:${fetchRoute.declaration.line} (rule: ${fetchRoute.declaration.rule}) -- the framework generates this handler at runtime, so no literal per-action source method exists to correlate to. Resolver NOT generated -- this is a structural boundary of static-scan-based handles codegen, not a bug. See D-resolver-scope.`
+				: 'the single-resource GET route\'s handler is an inline function expression, not a named export -- nothing to correlate to a defining file, resolver NOT generated.';
+			notes.push(`${entity.className}: ${note}`);
 		} else if (!handlerFile) {
 			notes.push(`${entity.className}: could not resolve ${fetchRoute.method}'s own defining file (import, or one barrel hop, from ${path.relative(repoRoot, fetchRoute.file)}) -- resolver NOT generated.`);
 		} else if (!selectFields) {

package/handles/providers/typescript-express/rules.mjs

@@ -0,0 +1,129 @@
+// D-business-rules (R9): the emit-side half of compiled business rules for typescript-express.
+// Mirrors handles/providers/python-fastapi/rules.mjs's own shape -- 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 `rulesSchemas/` -- 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 { 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` -- ruleSet.ts
+// discovers every `rulesSchemas/*.rules.json` file at module-load 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 need any {{VAR}}
+// substitution -- same reasoning observe's own INFRA_FILES give.
+const INFRA_FILES = [
+	{ template: 'ruleCheck.ts.tmpl', target: 'ruleCheck.ts' },
+	{ template: 'ruleSet.ts.tmpl', target: 'ruleSet.ts' },
+	{ template: 'enforceRules.ts.tmpl', target: 'enforceRules.ts' },
+];
+
+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);
+}
+
+function camelCase(name) {
+	const pascal = pascalCase(name);
+	return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+// R5/Phase 3: one module per resource, one exported function per derived field -- same "complete,
+// never a stub" posture java-spring's/python-fastapi's own renderers hold. All params are typed
+// `number`: 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((p) => `${p}: number`).join(', ');
+		const formula = renderExprInfix(rule.expr);
+		return `/** \`${rule.field} = ${formula}\` -- rule "${rule.id}". */\nexport function compute${pascalCase(rule.field)}(${params}): number {\n\treturn ${formula};\n}`;
+	});
+	return `// Generated by backend-skeleton (bskel rules emit) for feature ${featureId}.
+//
+// D-business-rules (R5): a complete, compiling 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')}
+`;
+}
+
+/**
+ * `plan` is the already-computed typescript-express resource plan (bin/bskel.mjs calls
+ * planTypeScriptExpress() before this) -- only plan.srcRoot is 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.
+ */
+export function emitRulesTypeScriptExpress({ repoRoot, featureId, artifact, plan, force = false, reason = '', dryRun = false, computeDiff = false }) {
+	const rulesDir = path.join(plan.srcRoot, 'rules');
+
+	const infraUnits = INFRA_FILES.map((f) => ({
+		id: f.template,
+		templatePath: path.join(TEMPLATES_DIR, f.template),
+		targetAbs: path.join(rulesDir, f.target),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), {}),
+	}));
+
+	// R5/Phase 3: one <resource>Rules.ts 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, `${camelCase(resource)}Rules.ts`),
+		content: renderDerivedModule(resource, rules, featureId),
+	}));
+
+	const result = emitUnits({ repoRoot, featureId, provider: 'typescript-express', 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 every other provider's emitter holds.
+	const content = `${JSON.stringify(artifact, null, '\t')}\n`;
+	const target = path.join(rulesDir, 'rulesSchemas', `${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: insert enforceRules("<operationId>") into the real route's own middleware array to have them checked automatically on every request.`,
+			`defaults to OBSERVE (logs violations to stderr, 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 enforceRules() -- they need the resource's CURRENT state, which no middleware can supply generically. Call ruleCheck.checkTransitions(rules, req.body, {"/status": current.status}) directly wherever your route handler 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) => `${camelCase(u.resource)}Rules.ts`).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/typescript-express/templates/enforceRules.ts.tmpl

@@ -0,0 +1,93 @@
+// 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 route a human has chosen to insert enforceRules('...') into. Mirrors observeContract.ts's own
+// choice: Express middleware IS this ecosystem's own interception mechanism, so there is no
+// separate "declare a marker" vs. "implement the interceptor" split worth preserving here either.
+//
+// SIMPLER than observeContract.ts's response-capture dance: this middleware only ever checks the
+// REQUEST (field/cross rules have no response-shape concept), so there is no res.json patching,
+// no res.on('finish', ...) -- a violation in enforce mode is rejected synchronously, before
+// `next()` is ever called, the same way any ordinary Express validation middleware works.
+//
+// Checks FIELD and CROSS rules only. Does NOT check TRANSITION rules -- a transition guard needs
+// the resource's CURRENT persisted state, which this middleware's own request-scoped context has
+// no generic way to obtain. Call checkTransitions() directly, with the current state your own
+// route handler already has, wherever a transition needs checking.
+//
+// The observe/enforce split is read from the BSKEL_RULES_MODE environment variable (default
+// "observe") on every request, not baked in at emit 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 `bskel.rules.mode` / python-fastapi's own BSKEL_RULES_MODE take.
+//
+// - observe (default): every violation is logged to stderr, the request always proceeds.
+// - enforce: a violation responds 400 BEFORE the route handler runs. The response body 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 Violation carries.
+//
+// Fail-open on an INTERNAL error, fail-closed on a REAL violation: if this middleware itself
+// cannot compute violations (a malformed body, a loader problem), that is logged and the request
+// proceeds unaffected, in BOTH modes.
+//
+// Example:
+//   router.patch('/widgets/:id', [enforceRules('updateWidget')], updateWidget);
+
+import type { RequestHandler, Request, Response, NextFunction } from 'express';
+import * as ruleCheck from './ruleCheck';
+import * as ruleSet from './ruleSet';
+import type { RuleOperation, Violation } from './ruleCheck';
+
+function mode(): string {
+	return process.env.BSKEL_RULES_MODE ?? 'observe';
+}
+
+function safelyCheck(rules: RuleOperation, body: unknown, operationId: string): Violation[] {
+	try {
+		if (body === undefined) return [];
+		return ruleCheck.check(rules, body);
+	} catch (err) {
+		console.warn(`enforceRules: could not evaluate rules for operation "${operationId}" -- the request proceeds unaffected`, err);
+		return [];
+	}
+}
+
+function logViolations(operationId: string, violations: Violation[], activeMode: string): void {
+	try {
+		for (const v of violations) {
+			console.warn(`bskel.rules.violations operation=${operationId} rule=${v.ruleId} pointer=${v.pointer} kind=${v.kind} mode=${activeMode} -- ${v.message}`);
+		}
+	} catch (err) {
+		console.warn(`enforceRules: could not log violations for operation "${operationId}"`, err);
+	}
+}
+
+/** Built from rule id / pointer / bound-derived text only -- never an observed value, the same
+ * redaction invariant every Violation.message already holds. */
+function summarize(operationId: string, violations: Violation[]): string {
+	const parts = violations.map((v) => `${v.pointer} (${v.ruleId}): ${v.message}`);
+	return `business rule violation(s) for ${operationId}: ${parts.join('; ')}`;
+}
+
+export function enforceRules(operationId: string): RequestHandler {
+	return (req: Request, res: Response, next: NextFunction) => {
+		const rules = ruleSet.forOperation(operationId);
+		if (rules.field.length === 0 && rules.cross.length === 0) {
+			// Nothing compiled for this operation -- most commonly a feature with no rules.yaml and
+			// a contract that projected nothing enforceable. Proceeds silently.
+			next();
+			return;
+		}
+
+		const violations = safelyCheck(rules, req.body, operationId);
+		if (violations.length > 0) {
+			const activeMode = mode();
+			logViolations(operationId, violations, activeMode);
+			if (activeMode === 'enforce') {
+				res.status(400).json({ error: summarize(operationId, violations) });
+				return; // next() is never called -- the route handler must not run
+			}
+		}
+		next();
+	};
+}