backend-skeleton 1.3.0 → 1.5.0

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

@@ -339,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: {

package/lib/gate-definitions.mjs

@@ -295,6 +295,32 @@ export const GATE_DEFINITIONS = Object.freeze({
 			return inputs;
 		},
 	},
+	// D-business-rules (R7): a feature's compiled business rules. Its own gate rather than a
+	// widening of `dependencies` -- the same call cross_feature/dependencies/patch_transactions/
+	// conformance each made rather than overloading a neighbour, and the two genuinely differ:
+	// a dependency is an edge between two fields, a rule is a constraint checked against one
+	// feature's own contract. REQUIRED_WHEN_PRESENT because most features will never declare one.
+	//
+	// Positioned between `dependencies` and `handles`: after dependencies because a derived-field
+	// rule references a declared dependency edge, before handles because that is where generated
+	// code appears.
+	//
+	// contract_hash is an input, not just the two rules files: every pointer, scalar type, and
+	// enum state in a compiled rule was verified against the contract at compile time, so
+	// re-emitting the contract can invalidate a rule that still looks fine on its own. Without
+	// this token a contract change could silently leave a rule enforcing against a field that no
+	// longer exists. (`contract` is itself a REQUIRED gate, so this is defence in depth, not the
+	// only line -- the same relationship `handles`'s own contract_hash token already has.)
+	rules: {
+		name: 'rules',
+		scope: SCOPE.FEATURE,
+		verifyPolicy: VERIFY_POLICY.REQUIRED_WHEN_PRESENT,
+		recompute: (root, featureId) => ({
+			rules_source_hash: sha256File(specPath(root, featureId, 'rules.yaml')),
+			rules_compiled_hash: sha256File(specPath(root, featureId, 'rules', `${featureId}.rules.json`)),
+			contract_hash: sha256File(specPath(root, featureId, 'contracts', `${featureId}.schema.json`)),
+		}),
+	},
 	// Staleness = the generated Java (or the contract it was generated from) has moved since
 	// emit -- NOT "does the migration still match the DB schema" (unknowable without a live DB
 	// connection this tool deliberately never opens on its own, see D-migration-scope). Note
@@ -403,7 +429,7 @@ export const GATE_DEFINITIONS = Object.freeze({
 // test/gate-definitions.test.mjs asserts this stays exactly in sync with GATE_DEFINITIONS' own
 // key set, so a gate added to one and not the other fails loudly instead of silently vanishing
 // from `bskel verify` the way `stack` did before this module existed.
-export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'handles', 'stack', 'patch_transactions', 'conformance']);
+export const GATE_NAMES = Object.freeze(['preflight', 'scan', 'cross_feature', 'contract', 'dependencies', 'rules', 'handles', 'stack', 'patch_transactions', 'conformance']);
 
 export function getGateDefinition(name) {
 	return Object.hasOwn(GATE_DEFINITIONS, name) ? GATE_DEFINITIONS[name] : null;

package/lib/workflow.mjs

@@ -44,6 +44,11 @@ const ESTABLISH_COMMAND = {
 	// directly on the first real stale occurrence and throws a raw TypeError instead of a clean
 	// stale report.
 	dependencies: (id) => `bskel dependency declare --feature ${id} --resource <Type> --field <name> --source-feature <id> --source-resource <Type> --source-field <name> --reason "..."`,
+	// D-business-rules (R7): wired in the SAME commit as the `rules` gate itself, per the repeated
+	// warnings above -- this exact gap has now been found live three times (dependencies,
+	// conformance, and the cross_feature near-miss) and is the single most reliably-recurring
+	// mistake in this file.
+	rules: (id) => `bskel rules check --feature ${id}`,
 	handles: (id) => `bskel handles plan --feature ${id}   # then: bskel handles emit --feature ${id}`,
 	stack: () => 'bskel stack apply --choice <id> --apply',
 	// D-patch-transactions: added in the SAME commit as the gate itself -- per the
@@ -89,6 +94,10 @@ const MUTATING_PREFIXES = [
 	'bskel gate force', 'bskel dependency declare', 'bskel dependency remove', 'bskel handles emit',
 	'bskel handles plan', 'bskel stack apply', 'bskel observe emit', 'bskel observe import',
 	'bskel patch propose', 'bskel patch approve', 'bskel patch apply', 'bskel patch rollback',
+	// D-business-rules (R7): `rules check` writes the compiled artifact and passes its gate;
+	// `rules emit` writes generated source. `rules list`/`rules explain` are read-only and
+	// correctly absent -- the same per-verb split `pattern list|show|suggest` was checked against.
+	'bskel rules check', 'bskel rules emit',
 ];
 
 // Exported (not just inlined into action()) so lib/workflow.mjs's own test suite can assert the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-skeleton",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "Deterministic gate layer for AI-assisted backend changes -- blocks brownfield collisions and contract/handle drift via disk-hash checks before code ships. Scaffolding codegen included (Java/Spring, Python/FastAPI, TypeScript/Express).",
   "license": "AGPL-3.0-or-later",
@@ -27,6 +27,7 @@
     "new/",
     "stack/",
     "patterns/",
+    "rules/",
     "schemas/",
     "scripts/preflight-base-ref.sh",
     "LICENSE",