backend-skeleton 1.2.0 → 1.4.0

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

package/handles/providers/typescript-express/templates/ruleCheck.ts.tmpl

@@ -0,0 +1,209 @@
+// Generated by backend-skeleton (bskel rules emit). Do not hand-edit -- change the source rule
+// and regenerate.
+//
+// D-business-rules (R3/R9): pure, dependency-free 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 (and its python-fastapi sibling
+// rule_check.py.tmpl) field-for-field, so all three runtimes are guaranteed to agree.
+//
+// Redaction invariant, inherited from contractCheck.ts 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.
+
+export interface Violation {
+	ruleId: string;
+	pointer: string;
+	kind: string;
+	message: string;
+}
+
+export interface FieldRule {
+	id: string;
+	pointer: string;
+	assert: string;
+	value: unknown;
+	origin: string;
+}
+
+export interface CrossRule {
+	id: string;
+	pointers: string[];
+	assert: string;
+	types: string[];
+	origin: string;
+}
+
+export interface TransitionRule {
+	id: string;
+	pointer: string;
+	from: string[];
+	to: string[];
+	origin: string;
+}
+
+export interface RuleOperation {
+	field: FieldRule[];
+	cross: CrossRule[];
+	transition: TransitionRule[];
+}
+
+/** Compiled pointers are always a single top-level "/field" segment (rules/compile.mjs refuses
+ * anything deeper) -- this is a lookup, not a JSON Pointer implementation. */
+function at(body: Record<string, unknown>, pointer: string): unknown {
+	const value = body[pointer.slice(1)];
+	return value === null || value === undefined ? undefined : value;
+}
+
+const CROSS_SYMBOLS: Record<string, string> = { lt: '<', lte: '<=', gt: '>', gte: '>=', eq: 'equal to', neq: 'different from' };
+
+/** Runs every FIELD and CROSS rule in `rules` against a request body. TRANSITION rules are
+ * deliberately NOT run here -- see checkTransitions() for why they need an argument this function
+ * does not have. */
+export function check(rules: RuleOperation, body: unknown): Violation[] {
+	const violations: Violation[] = [];
+	if (typeof body !== 'object' || body === null || Array.isArray(body)) return violations;
+	const record = body as Record<string, unknown>;
+	for (const rule of rules.field) violations.push(...checkField(rule, record));
+	for (const rule of rules.cross) violations.push(...checkCross(rule, record));
+	return violations;
+}
+
+function checkField(rule: FieldRule, body: Record<string, unknown>): Violation[] {
+	const value = at(body, rule.pointer);
+	// An absent optional field is not a violation -- requiredness is the contract's own statement,
+	// enforced by contractCheck.ts, deliberately not duplicated in this vocabulary.
+	if (value === undefined) return [];
+
+	switch (rule.assert) {
+		case 'minLength': {
+			const bound = rule.value as number;
+			if (typeof value === 'string' && value.length < bound) {
+				return [{ ruleId: rule.id, pointer: rule.pointer, kind: 'minLength', message: `shorter than the required minimum length of ${bound}` }];
+			}
+			return [];
+		}
+		case 'maxLength': {
+			const bound = rule.value as number;
+			if (typeof value === 'string' && value.length > bound) {
+				return [{ ruleId: rule.id, pointer: rule.pointer, kind: 'maxLength', message: `longer than the permitted maximum length of ${bound}` }];
+			}
+			return [];
+		}
+		case 'minimum':
+			return compareNumber(rule, value, (a, b) => a < b, 'is below the permitted minimum of ');
+		case 'maximum':
+			return compareNumber(rule, value, (a, b) => a > b, 'is above the permitted maximum of ');
+		case 'exclusiveMinimum':
+			return compareNumber(rule, value, (a, b) => a <= b, 'must be strictly greater than ');
+		case 'exclusiveMaximum':
+			return compareNumber(rule, value, (a, b) => a >= b, 'must be strictly less than ');
+		case 'multipleOf': {
+			const bound = rule.value as number;
+			if (typeof value === 'number' && Number.isFinite(value) && bound) {
+				const remainder = value % bound;
+				if (Math.min(Math.abs(remainder), Math.abs(remainder - bound)) > 1e-9) {
+					return [{ ruleId: rule.id, pointer: rule.pointer, kind: 'multipleOf', message: `is not an exact multiple of ${bound}` }];
+				}
+			}
+			return [];
+		}
+		case 'enum': {
+			const allowed = (rule.value as unknown[]) ?? [];
+			if (!allowed.includes(value)) {
+				return [{ ruleId: rule.id, pointer: rule.pointer, kind: 'enum', message: `is not one of the ${allowed.length} permitted values` }];
+			}
+			return [];
+		}
+		default:
+			// 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.
+			return [{ ruleId: rule.id, pointer: rule.pointer, kind: 'unsupported', message: `rule assertion "${rule.assert}" is not understood by this generated checker -- re-run \`bskel rules emit\` to regenerate it` }];
+	}
+}
+
+function compareNumber(rule: FieldRule, value: unknown, violates: (a: number, b: number) => boolean, messagePrefix: string): Violation[] {
+	if (typeof value !== 'number' || !Number.isFinite(value)) return [];
+	const bound = rule.value as number;
+	if (violates(value, bound)) {
+		return [{ ruleId: rule.id, pointer: rule.pointer, kind: rule.assert, message: `${messagePrefix}${bound}` }];
+	}
+	return [];
+}
+
+function checkCross(rule: CrossRule, body: Record<string, unknown>): Violation[] {
+	const [first, second] = rule.pointers;
+	const a = at(body, first);
+
+	if (rule.assert === 'requiredIf') {
+		if (a !== undefined && at(body, second) === undefined) {
+			return [{ ruleId: rule.id, pointer: second, kind: 'requiredIf', message: `is required because ${first} is present` }];
+		}
+		return [];
+	}
+	if (rule.assert === 'mutuallyExclusive') {
+		const present = rule.pointers.filter((p) => at(body, p) !== undefined);
+		if (present.length > 1) {
+			return [{ ruleId: rule.id, pointer: first, kind: 'mutuallyExclusive', message: `at most one of ${rule.pointers.join(', ')} may be present, got ${present.length}` }];
+		}
+		return [];
+	}
+
+	const b = at(body, second);
+	// Either side absent means there is nothing to compare -- same reasoning as RuleCheck.java.
+	if (a === undefined || b === undefined) return [];
+
+	let cmp: number;
+	if (typeof a === 'number' && typeof b === 'number') {
+		cmp = a === b ? 0 : a > b ? 1 : -1;
+	} else if (typeof a === 'string' && typeof b === 'string') {
+		cmp = a === b ? 0 : a > b ? 1 : -1;
+	} 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.
+		return [{ ruleId: rule.id, pointer: first, kind: 'incomparable', message: `could not be compared with ${second} -- the payload types differ from the contract's declared types` }];
+	}
+
+	if (!(rule.assert in CROSS_SYMBOLS)) {
+		return [{ ruleId: rule.id, pointer: first, kind: 'unsupported', message: `rule assertion "${rule.assert}" is not understood by this generated checker -- re-run \`bskel rules emit\` to regenerate it` }];
+	}
+	const violated = ({ lt: cmp >= 0, lte: cmp > 0, gt: cmp <= 0, gte: cmp < 0, eq: cmp !== 0, neq: cmp === 0 } as Record<string, boolean>)[rule.assert];
+	if (violated) {
+		return [{ ruleId: rule.id, pointer: first, kind: rule.assert, message: `must be ${CROSS_SYMBOLS[rule.assert]} ${second}` }];
+	}
+	return [];
+}
+
+/**
+ * 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.
+ *
+ * `currentStates` 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.ts's own patchField draws.
+ *
+ * Fail-closed: a pointer with no entry in `currentStates` produces an "unchecked" violation, never
+ * a silent pass.
+ */
+export function checkTransitions(rules: RuleOperation, body: unknown, currentStates: Record<string, string> | null): Violation[] {
+	const violations: Violation[] = [];
+	if (typeof body !== 'object' || body === null || Array.isArray(body)) return violations;
+	const record = body as Record<string, unknown>;
+	for (const rule of rules.transition) {
+		const target = at(record, rule.pointer);
+		if (typeof target !== 'string') continue; // not changing this field
+		if (currentStates === null || !(rule.pointer in currentStates)) {
+			violations.push({ ruleId: rule.id, pointer: rule.pointer, kind: 'unchecked', message: 'a transition guard is declared but the current state was not supplied, so it could not be evaluated -- pass it via checkTransitions(..., currentStates)' });
+			continue;
+		}
+		const fromState = currentStates[rule.pointer];
+		const toState = target;
+		if (fromState === toState) continue; // no transition is occurring
+		if (rule.from.includes(fromState) && rule.to.includes(toState)) continue; // explicitly allowed
+		violations.push({ ruleId: rule.id, pointer: rule.pointer, kind: 'transition', message: `this state change is not permitted -- allowed transitions are from {${rule.from.join(', ')}} to {${rule.to.join(', ')}}` });
+	}
+	return violations;
+}

package/handles/providers/typescript-express/templates/ruleSet.ts.tmpl

@@ -0,0 +1,61 @@
+// 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
+// `rulesSchemas/` directory (one per feature `bskel rules emit` has been run against) at MODULE
+// LOAD time and merges them into one flat map keyed by operationId. Mirrors observedSchema.ts's
+// own shape exactly -- same `fs.readdirSync` discovery, same CommonJS `__dirname` anchor (see that
+// module's own doc comment 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 ruleCheck.ts's own doc comment
+// for that boundary.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RuleOperation } from './ruleCheck';
+
+const SCHEMAS_DIR = path.join(__dirname, 'rulesSchemas');
+
+const EMPTY_OPERATION: RuleOperation = { field: [], cross: [], transition: [] };
+
+function loadOne(filePath: string): Record<string, RuleOperation> {
+	let raw: any;
+	try {
+		raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+	} catch (err) {
+		console.warn(`ruleSet: could not read/parse ${filePath} -- its rules will not be enforced`, err);
+		return {};
+	}
+	const operations: Record<string, RuleOperation> = {};
+	for (const [operationId, entry] of Object.entries<any>(raw.operations ?? {})) {
+		operations[operationId] = {
+			field: entry.field ?? [],
+			cross: entry.cross ?? [],
+			transition: entry.transition ?? [],
+		};
+	}
+	return operations;
+}
+
+function loadAll(): Map<string, RuleOperation> {
+	const merged = new Map<string, RuleOperation>();
+	if (!fs.existsSync(SCHEMAS_DIR)) return merged;
+	const files = fs.readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.rules.json')).sort();
+	for (const file of files) {
+		for (const [operationId, ops] of Object.entries(loadOne(path.join(SCHEMAS_DIR, file)))) {
+			if (merged.has(operationId)) {
+				console.warn(`ruleSet: operationId "${operationId}" is declared by more than one *.rules.json on disk -- the last one loaded wins`);
+			}
+			merged.set(operationId, ops);
+		}
+	}
+	return merged;
+}
+
+const OPERATIONS = loadAll();
+
+/** Never undefined -- an operation with no rules returns the shared empty operation object. */
+export function forOperation(operationId: string): RuleOperation {
+	return OPERATIONS.get(operationId) ?? EMPTY_OPERATION;
+}

package/lib/cli.mjs

@@ -241,6 +241,33 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-contract-csv: deliberately fewer flags than `contract export` -- no `--allow-unprefixed`
+	// (there is no hard refusal here to override, only a warning that always fires), no
+	// `--status-codes` (not an OpenAPI-shaped concept). `--bom` is CSV-specific: opt-in UTF-8 BOM
+	// for Excel-on-Windows, see D-contract-csv in DECISIONS.md.
+	'contract export-csv': {
+		usage: 'bskel contract export-csv --feature <id> [--out <path>] [--bom] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			bom: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// D-db-erd: the other "recognizable artifact" export, read-only, repo-independent like
+	// `bskel new` (no --feature -- the database plane is not feature-scoped, see E6 in D-db-erd,
+	// DECISIONS.md). Deliberately no `--db` flag: `db` IS the verb, so it's implied -- internally
+	// reuses `resolveDbSchemaOrExit(root, {...flags, db:true})` unchanged, so env-var handling and
+	// error strings stay byte-identical to `scan --db`.
+	'db erd': {
+		usage: 'bskel db erd [--database-url-env <NAME>] [--schema public] [--out <path>] [--json]',
+		options: {
+			'database-url-env': { type: 'string', default: null },
+			schema: { type: 'string', default: 'public' },
+			out: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	// D-contract-history: read-only, so no --module/--openapi-file/etc -- it only ever reads what
 	// git already recorded for this feature's own contract file.
 	'contract history': {
@@ -312,6 +339,43 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-business-rules: `check` compiles + verifies + establishes the `rules` gate; `list`/`explain`
+	// are read-only. `--init` writes a starter rules.yaml only when none exists (never overwrites).
+	'rules check': {
+		usage: 'bskel rules check --feature <id> [--init] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			init: { type: 'boolean', default: false },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'rules list': {
+		usage: 'bskel rules list --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'rules explain': {
+		usage: 'bskel rules explain --feature <id> --rule <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			rule: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'rules emit': {
+		usage: 'bskel rules emit --feature <id> [--module <name>] [--check] [--diff] [--force --reason "..."] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			module: { type: 'string', default: null },
+			check: { type: 'boolean', default: false },
+			diff: { type: 'boolean', default: false },
+			force: { type: 'boolean', default: false },
+			reason: { type: 'string', default: '' },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'stack apply': {
 		usage: 'bskel stack apply --choice <id> [--apply] [--port N] [--force --reason "..."] [--json]',
 		options: {
@@ -425,12 +489,18 @@ export const COMMANDS = {
 	// nobody actually asked for. The real defaults live in new/spring.mjs / new/fastapi.mjs, one
 	// place each.
 	new: {
-		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none]',
+		usage: 'bskel new --stack spring|fastapi --slug <name> [--dir <path>] [--offline] [--json] [--name <text>] [--description <text>] [--project-version <v>] [--group-id <pkg>] [--artifact-id <id>] [--package-name <pkg>] [--java-version <n>] [--packaging jar|war] [--dependencies a,b,c] [--add-dependencies a,b,c] [--python-version <spec>] [--port N] [--license <spdx>] [--database postgres|sqlite|none] [--record-pattern --pattern-database-url-env <NAME>]',
 		options: {
 			stack: { type: 'string', default: null, required: true },
 			slug: { type: 'string', default: null, required: true },
 			dir: { type: 'string', default: null },
 			offline: { type: 'boolean', default: false },
+			// D-pattern-accrual: both opt-in, both required together -- omitting either leaves
+			// `bskel new` byte-identical to today (no recording, no DB connection attempted). The
+			// actual write is best-effort (never fails the scaffold); only the "flag given but the
+			// other half missing / env var unset" usage mistake is checked before scaffold.
+			'record-pattern': { type: 'boolean', default: false },
+			'pattern-database-url-env': { type: 'string', default: null },
 
 			// Both stacks.
 			name: { type: 'string', default: null },
@@ -466,6 +536,34 @@ export const COMMANDS = {
 			'boot-version': { type: 'string', default: null, hidden: true },
 		},
 	},
+	// D-pattern-accrual: all three read-only, all requiring --pattern-database-url-env --
+	// there is no meaningful "run without a live connection" mode, same posture as `handles audit`
+	// (O7). Distinct flag name from every other command's --database-url-env: that flag always means
+	// the TARGET APPLICATION's database; this one is the user's own cross-project pattern store.
+	'pattern list': {
+		usage: 'bskel pattern list --pattern-database-url-env <NAME> [--stack spring|fastapi] [--json]',
+		options: {
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			stack: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	'pattern show': {
+		usage: 'bskel pattern show <pattern_id> --pattern-database-url-env <NAME> [--json]',
+		options: {
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+		allowPositionals: true,
+	},
+	'pattern suggest': {
+		usage: 'bskel pattern suggest --stack spring|fastapi --pattern-database-url-env <NAME> [--json]',
+		options: {
+			stack: { type: 'string', default: null, required: true },
+			'pattern-database-url-env': { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'handles patch approve': {
 		usage: 'bskel handles patch approve --feature <id> [--module <name>] --resource <Type> --field <name> --strategy patch-wrapper|null-means-unchanged --reason "..." [--json]',
 		options: {

package/lib/doctor.mjs

@@ -2,10 +2,18 @@
 // D1's lib/workflow.mjs separates `computeWorkflowState()` from its cmdStatus/cmdNext callers --
 // this stays pure enough to unit test without spawning the CLI, and bin/bskel.mjs just renders
 // whatever this returns.
-import { execFileSync } from 'node:child_process';
 import { detectBuildCommand } from './verify.mjs';
 import { listCatalogChoices, loadCatalogEntry } from '../stack/apply.mjs';
 import { detectAstHelperAvailable } from '../handles/providers/java-spring/ast-bridge.mjs';
+// D-zero-config-scan: re-exported from scanners/text-util.mjs (a cycle-free leaf module), NOT
+// defined here -- this file transitively imports scanners/registry.mjs (via ./verify.mjs), which
+// dynamically import()s every scanner adapter; an adapter importing binaryAvailable() FROM here
+// would close that cycle. See scanners/text-util.mjs's own comment on binaryAvailable() for the
+// real hang this caused before the fix. Every existing caller of `binaryAvailable` from this file
+// (bin/bskel.mjs) needs no change -- it's still available at this same import path.
+import { binaryAvailable } from '../scanners/text-util.mjs';
+
+export { binaryAvailable };
 
 // D5: the three workflows that have tool requirements beyond "git + a supported Node runtime"
 // (every workflow needs those two -- preflight/contract don't need anything ELSE, so they're
@@ -34,15 +42,8 @@ function nodeVersionOk(versionString) {
 }
 
 function binaryCheck(name, { required, remediation }) {
-	let ok = true;
-	let detail = '';
-	try {
-		execFileSync(name, ['--version'], { stdio: 'pipe' });
-	} catch {
-		ok = false;
-		detail = 'not found on PATH';
-	}
-	return { name: `binary: ${name}`, required, ok, detail, remediation: ok ? null : remediation };
+	const ok = binaryAvailable(name);
+	return { name: `binary: ${name}`, required, ok, detail: ok ? '' : 'not found on PATH', remediation: ok ? null : remediation };
 }
 
 function nodeVersionCheck() {