backend-skeleton 1.2.0 → 1.4.0

package/rules/compile.mjs

@@ -0,0 +1,433 @@
+// D-business-rules (R3/R4/R6): the compiler. Turns a hand-authored rules source document plus the
+// feature's own contract into the bounded, deterministic artifact every target-language runtime
+// executes.
+//
+// This is the ONE place rule semantics are decided -- the same doctrine
+// handles/observe-schema-projection.mjs states for its own projection: "What's checkable is
+// decided ONCE here, in JS ... each provider's own generated checker is a dumb, mechanical
+// executor of an already-simplified instruction set, never a second independent JSON-Schema
+// interpreter." Three languages can only be guaranteed to agree if they are given instructions,
+// not expressions.
+//
+// PURE. No filesystem, no git, no CLI, no process.exit -- the caller owns I/O and exit codes, the
+// same split contracts/emit.mjs holds against bin/bskel.mjs.
+import {
+	FIELD_ASSERTS, CROSS_ASSERTS, PREDICATE_KINDS, ALL_RULE_KINDS, RULE_SCALAR_TYPES, DERIVED_OPS,
+	FIELD_ASSERT_NAMES, CROSS_ASSERT_NAMES,
+	getFieldAssert, getCrossAssert, valueMatchesType, typesAreComparable,
+} from './vocabulary.mjs';
+import { makeRuleDiagnostic, isBlocking } from './diagnostics.mjs';
+import { collectParams } from './derived.mjs';
+
+export const RULES_SCHEMA_VERSION = '1';
+export const RULES_SOURCE_SCHEMA = 'sbf.feature-rules-source/1';
+
+// JSON Schema keywords `handles/observe-schema-projection.mjs` already projects and every
+// generated checker already enforces. Seeing one of these while projecting contract constraints is
+// not an expressiveness gap -- it is already covered, one layer down -- so it is skipped silently
+// rather than reported as unsupported. Keeping this list explicit (rather than "anything not in
+// FIELD_ASSERTS") is what makes a genuinely-new keyword show up as a warning instead of vanishing.
+const OBSERVE_OWNED_KEYWORDS = Object.freeze(new Set(['type', 'pattern', 'required', 'properties', 'additionalProperties', 'description', 'example', 'examples', 'title', 'default', 'nullable', 'deprecated', 'readOnly', 'writeOnly', '$id', '$schema', '$comment', 'format']));
+
+// Only top-level `/field` pointers are addressable, matching observe-schema-projection.mjs's own
+// scalar-leaf boundary exactly -- that module projects `schema.properties[key]` one level deep and
+// marks anything deeper `unsupported`. Addressing deeper here would mean this vocabulary could
+// describe constraints the runtime checkers have no projected value to evaluate against.
+const TOP_LEVEL_POINTER_RE = /^\/[^/]+$/;
+
+function pointerField(pointer) {
+	return typeof pointer === 'string' && TOP_LEVEL_POINTER_RE.test(pointer) ? pointer.slice(1) : null;
+}
+
+// Resolves a pointer against an operation's projected request body schema, returning the scalar
+// leaf's own {type, enum} or a diagnostic-shaped reason it could not. Fail-closed: an operation
+// with no requestBodySchema resolves NOTHING (rather than accepting every pointer blind), which is
+// what RULE_NO_CONTRACT_SCHEMA reports.
+function resolvePointer(opContract, pointer) {
+	const schema = opContract?.requestBodySchema;
+	if (!schema || typeof schema !== 'object' || schema.type !== 'object' || !schema.properties) {
+		return { ok: false, code: 'RULE_NO_CONTRACT_SCHEMA' };
+	}
+	const field = pointerField(pointer);
+	if (!field || !Object.hasOwn(schema.properties, field)) {
+		return { ok: false, code: 'RULE_UNKNOWN_POINTER', known: Object.keys(schema.properties).sort() };
+	}
+	const propSchema = schema.properties[field];
+	if (!propSchema || typeof propSchema !== 'object' || !RULE_SCALAR_TYPES.includes(propSchema.type)) {
+		return { ok: false, code: 'RULE_UNKNOWN_POINTER', known: Object.keys(schema.properties).sort(), nonScalar: true };
+	}
+	return { ok: true, type: propSchema.type, enum: Array.isArray(propSchema.enum) ? propSchema.enum : null };
+}
+
+// R4: every constraint the user's own OpenAPI document already asserts, transported into a rule.
+// Not synthesis -- the same "copying is not synthesizing" posture D-openapi-passthrough (A7)
+// established for the contract itself. A constraint this vocabulary cannot express is recorded in
+// `unsupported[]`, never dropped.
+export function projectContractRules(operationId, opContract) {
+	const rules = [];
+	const diagnostics = [];
+	const schema = opContract?.requestBodySchema;
+	if (!schema || typeof schema !== 'object' || schema.type !== 'object' || !schema.properties) {
+		return { rules, diagnostics };
+	}
+	for (const [field, propSchema] of Object.entries(schema.properties).sort(([a], [b]) => a.localeCompare(b))) {
+		const pointer = `/${field}`;
+		if (!propSchema || typeof propSchema !== 'object') continue;
+		if (!RULE_SCALAR_TYPES.includes(propSchema.type)) {
+			// Deeper than a scalar leaf -- observe already marks this pointer `unsupported` in its own
+			// projection; recorded here too so a rules audit is self-contained.
+			diagnostics.push(makeRuleDiagnostic('RULE_NON_SCALAR_TARGET', {
+				subject: `${operationId}${pointer}`,
+				message: `${operationId} ${pointer}: not a scalar leaf, so no field rule was projected for it`,
+				detail: { operation: operationId, pointer },
+			}));
+			continue;
+		}
+		for (const [keyword, value] of Object.entries(propSchema).sort(([a], [b]) => a.localeCompare(b))) {
+			if (OBSERVE_OWNED_KEYWORDS.has(keyword)) continue;
+			const spec = getFieldAssert(keyword);
+			if (!spec) {
+				diagnostics.push(makeRuleDiagnostic('RULE_UNSUPPORTED_CONSTRAINT', {
+					subject: `${operationId}${pointer}`,
+					message: `${operationId} ${pointer}: "${keyword}" has no equivalent in this rule vocabulary and is NOT enforced`,
+					detail: { operation: operationId, pointer, keyword },
+				}));
+				continue;
+			}
+			if (!spec.appliesTo.includes(propSchema.type) || !valueMatchesType(spec.valueType, value)) {
+				// The document itself is internally inconsistent (e.g. minLength on an integer).
+				// Reported, not refused: this is someone else's document, not a rule the user authored
+				// here, so the same "a contract is built from whatever was found" posture applies.
+				diagnostics.push(makeRuleDiagnostic('RULE_UNSUPPORTED_CONSTRAINT', {
+					subject: `${operationId}${pointer}`,
+					message: `${operationId} ${pointer}: "${keyword}" does not apply to a ${propSchema.type} field, so it was NOT enforced`,
+					detail: { operation: operationId, pointer, keyword, fieldType: propSchema.type },
+				}));
+				continue;
+			}
+			rules.push({
+				id: `contract:${operationId}:${field}:${keyword}`,
+				pointer,
+				assert: keyword,
+				value,
+				origin: 'contract',
+			});
+		}
+	}
+	return { rules, diagnostics };
+}
+
+function compileFieldRule(rule, opContract) {
+	const resolved = resolvePointer(opContract, rule.pointer);
+	if (!resolved.ok) {
+		return { error: makeRuleDiagnostic(resolved.code, {
+			subject: rule.id,
+			message: resolved.code === 'RULE_NO_CONTRACT_SCHEMA'
+				? `rule "${rule.id}": operation "${rule.operation}" has no projected requestBodySchema, so ${rule.pointer} cannot be verified`
+				: `rule "${rule.id}": ${rule.pointer} is not a scalar field of operation "${rule.operation}"${resolved.known ? ` -- known fields: ${resolved.known.join(', ')}` : ''}`,
+			detail: { rule: rule.id, operation: rule.operation, pointer: rule.pointer, ...(resolved.known ? { knownFields: resolved.known } : {}) },
+		}) };
+	}
+	const spec = getFieldAssert(rule.assert);
+	if (!spec) {
+		return { error: makeRuleDiagnostic('RULE_UNKNOWN_ASSERT', {
+			subject: rule.id,
+			message: `rule "${rule.id}": unknown field assertion "${rule.assert}" -- known field assertions: ${FIELD_ASSERT_NAMES.join(', ')}`,
+			detail: { rule: rule.id, assert: rule.assert, known: FIELD_ASSERT_NAMES },
+		}) };
+	}
+	if (!spec.appliesTo.includes(resolved.type)) {
+		return { error: makeRuleDiagnostic('RULE_ASSERT_NOT_APPLICABLE', {
+			subject: rule.id,
+			message: `rule "${rule.id}": "${rule.assert}" cannot apply to ${rule.pointer}, which the contract declares as ${resolved.type} (it applies to: ${spec.appliesTo.join(', ')})`,
+			detail: { rule: rule.id, assert: rule.assert, fieldType: resolved.type, appliesTo: [...spec.appliesTo] },
+		}) };
+	}
+	if (!valueMatchesType(spec.valueType, rule.value)) {
+		return { error: makeRuleDiagnostic('RULE_VALUE_TYPE', {
+			subject: rule.id,
+			message: `rule "${rule.id}": "${rule.assert}" needs ${spec.valueType === 'integer' || spec.valueType === 'array' ? 'an' : 'a'} ${spec.valueType} value, got ${JSON.stringify(rule.value)}`,
+			detail: { rule: rule.id, assert: rule.assert, expected: spec.valueType, got: rule.value ?? null },
+		}) };
+	}
+	return { compiled: { id: rule.id, pointer: rule.pointer, assert: rule.assert, value: rule.value, origin: 'declared' } };
+}
+
+function compileCrossRule(rule, opContract) {
+	const spec = getCrossAssert(rule.assert);
+	if (!spec) {
+		return { error: makeRuleDiagnostic('RULE_UNKNOWN_ASSERT', {
+			subject: rule.id,
+			message: `rule "${rule.id}": unknown cross-field assertion "${rule.assert}" -- known cross-field assertions: ${CROSS_ASSERT_NAMES.join(', ')}`,
+			detail: { rule: rule.id, assert: rule.assert, known: CROSS_ASSERT_NAMES },
+		}) };
+	}
+	const pointers = Array.isArray(rule.pointers) ? rule.pointers : [];
+	const arityOk = spec.arity === 'n' ? pointers.length >= 2 : pointers.length === spec.arity;
+	if (!arityOk) {
+		return { error: makeRuleDiagnostic('RULE_ARITY', {
+			subject: rule.id,
+			message: `rule "${rule.id}": "${rule.assert}" needs ${spec.arity === 'n' ? 'two or more' : `exactly ${spec.arity}`} pointers, got ${pointers.length}`,
+			detail: { rule: rule.id, assert: rule.assert, arity: spec.arity, got: pointers.length },
+		}) };
+	}
+	const types = [];
+	for (const pointer of pointers) {
+		const resolved = resolvePointer(opContract, pointer);
+		if (!resolved.ok) {
+			return { error: makeRuleDiagnostic(resolved.code, {
+				subject: rule.id,
+				message: resolved.code === 'RULE_NO_CONTRACT_SCHEMA'
+					? `rule "${rule.id}": operation "${rule.operation}" has no projected requestBodySchema, so ${pointer} cannot be verified`
+					: `rule "${rule.id}": ${pointer} is not a scalar field of operation "${rule.operation}"${resolved.known ? ` -- known fields: ${resolved.known.join(', ')}` : ''}`,
+				detail: { rule: rule.id, operation: rule.operation, pointer, ...(resolved.known ? { knownFields: resolved.known } : {}) },
+			}) };
+		}
+		types.push(resolved.type);
+	}
+	if (spec.comparison && !typesAreComparable(types[0], types[1])) {
+		return { error: makeRuleDiagnostic('RULE_INCOMPARABLE_TYPES', {
+			subject: rule.id,
+			message: `rule "${rule.id}": cannot compare ${pointers[0]} (${types[0]}) with ${pointers[1]} (${types[1]}) -- both must be numeric, or both string`,
+			detail: { rule: rule.id, pointers: [...pointers], types },
+		}) };
+	}
+	return { compiled: { id: rule.id, pointers: [...pointers], assert: rule.assert, types, origin: 'declared' } };
+}
+
+function compileTransitionRule(rule, opContract) {
+	const resolved = resolvePointer(opContract, rule.pointer);
+	if (!resolved.ok) {
+		return { error: makeRuleDiagnostic(resolved.code, {
+			subject: rule.id,
+			message: resolved.code === 'RULE_NO_CONTRACT_SCHEMA'
+				? `rule "${rule.id}": operation "${rule.operation}" has no projected requestBodySchema, so ${rule.pointer} cannot be verified`
+				: `rule "${rule.id}": ${rule.pointer} is not a scalar field of operation "${rule.operation}"${resolved.known ? ` -- known fields: ${resolved.known.join(', ')}` : ''}`,
+			detail: { rule: rule.id, operation: rule.operation, pointer: rule.pointer, ...(resolved.known ? { knownFields: resolved.known } : {}) },
+		}) };
+	}
+	// A transition guard is an allow-list over a CLOSED set of states. Without an enum there is no
+	// closed set, so a typo'd state name would compile into a guard that silently never fires --
+	// refused rather than accepted, the same fail-closed call D-security-7 made for an
+	// unrecognized @PreAuthorize shape.
+	if (!resolved.enum) {
+		return { error: makeRuleDiagnostic('RULE_TRANSITION_NOT_ENUM', {
+			subject: rule.id,
+			message: `rule "${rule.id}": ${rule.pointer} declares no enum in the contract, so its transition states cannot be verified -- add an enum to the OpenAPI document and re-run \`bskel contract emit\``,
+			detail: { rule: rule.id, pointer: rule.pointer },
+		}) };
+	}
+	const from = Array.isArray(rule.from) ? rule.from : [];
+	const to = Array.isArray(rule.to) ? rule.to : [];
+	const unknown = [...from, ...to].filter((s) => !resolved.enum.includes(s));
+	if (unknown.length > 0) {
+		return { error: makeRuleDiagnostic('RULE_TRANSITION_UNKNOWN_STATE', {
+			subject: rule.id,
+			message: `rule "${rule.id}": state(s) ${unknown.map((s) => JSON.stringify(s)).join(', ')} are not in ${rule.pointer}'s declared enum -- known states: ${resolved.enum.join(', ')}`,
+			detail: { rule: rule.id, pointer: rule.pointer, unknown, known: [...resolved.enum] },
+		}) };
+	}
+	if (from.length === 0 || to.length === 0) {
+		return { error: makeRuleDiagnostic('RULE_ARITY', {
+			subject: rule.id,
+			message: `rule "${rule.id}": a transition rule needs at least one \`from\` and one \`to\` state`,
+			detail: { rule: rule.id, from: from.length, to: to.length },
+		}) };
+	}
+	return { compiled: { id: rule.id, pointer: rule.pointer, from: [...from], to: [...to], origin: 'declared' } };
+}
+
+const KIND_COMPILERS = Object.freeze({
+	field: compileFieldRule,
+	cross: compileCrossRule,
+	transition: compileTransitionRule,
+});
+
+// R5/Phase 3: validates an authored expr node against the closed grammar
+// ({op,args}/{ref}/{const}), recursively. Returns {ok:true} or {ok:false, error} -- the error is
+// a plain string (not yet a full diagnostic; the caller attaches rule id/subject context, since
+// this function has no access to the enclosing rule's own id).
+function validateDerivedExpr(node, fieldName) {
+	if (node && typeof node === 'object' && Object.hasOwn(node, 'ref')) {
+		if (typeof node.ref !== 'string' || node.ref.length === 0) return { ok: false, error: 'a `ref` leaf must be a non-empty string' };
+		if (node.ref === fieldName) return { ok: false, error: 'self-reference', code: 'RULE_DERIVED_SELF_REFERENCE' };
+		return { ok: true };
+	}
+	if (node && typeof node === 'object' && Object.hasOwn(node, 'const')) {
+		if (typeof node.const !== 'number' || !Number.isFinite(node.const)) return { ok: false, error: 'a `const` leaf must be a finite number' };
+		return { ok: true };
+	}
+	if (node && typeof node === 'object' && Object.hasOwn(node, 'op')) {
+		if (!DERIVED_OPS.includes(node.op)) return { ok: false, error: `unknown op "${node.op}" -- known ops: ${DERIVED_OPS.join(', ')}` };
+		if (!Array.isArray(node.args) || node.args.length !== 2) return { ok: false, error: `op "${node.op}" needs exactly 2 args, got ${Array.isArray(node.args) ? node.args.length : 'none'}` };
+		if (node.op === 'div' && node.args[1] && typeof node.args[1] === 'object' && node.args[1].const === 0) {
+			return { ok: false, error: 'division by a compile-time-known literal zero', code: 'RULE_DERIVED_DIVIDE_BY_ZERO' };
+		}
+		for (const arg of node.args) {
+			const result = validateDerivedExpr(arg, fieldName);
+			if (!result.ok) return result;
+		}
+		return { ok: true };
+	}
+	return { ok: false, error: 'must be one of {op,args}, {ref}, or {const}' };
+}
+
+function compileDerivedRule(rule) {
+	const id = typeof rule?.id === 'string' ? rule.id : '';
+	const resource = typeof rule?.resource === 'string' ? rule.resource : '';
+	const field = typeof rule?.field === 'string' ? rule.field : '';
+	if (!resource || !field || !rule?.expr || typeof rule.expr !== 'object') {
+		return { error: makeRuleDiagnostic('RULE_DERIVED_MISSING_FIELDS', {
+			subject: id || '(unnamed rule)',
+			message: `rule "${id || '(unnamed)'}": a derived rule needs a non-empty resource, field, and expr`,
+			detail: { rule: id, resource: resource || null, field: field || null, hasExpr: Boolean(rule?.expr) },
+		}) };
+	}
+	const validated = validateDerivedExpr(rule.expr, field);
+	if (!validated.ok) {
+		return { error: makeRuleDiagnostic(validated.code ?? 'RULE_DERIVED_INVALID_EXPR', {
+			subject: id,
+			message: `rule "${id}" (${resource}.${field}): ${validated.error}`,
+			detail: { rule: id, resource, field },
+		}) };
+	}
+	const params = collectParams(rule.expr);
+	return { compiled: { id, resource, field, params, expr: rule.expr, origin: 'declared' } };
+}
+
+/**
+ * Compiles an authored rules source document against a feature contract.
+ *
+ * @param {object} args
+ * @param {object} args.contract    a feature contract (schemas/feature-contract.schema.json shape)
+ * @param {object} args.source      the parsed rules.yaml document ({schema, rules: []}); null/absent is legal and yields a contract-only artifact
+ * @param {string} args.contractRef sha256 of the contract file on disk, so a compiled artifact can never be silently paired with a different contract
+ * @returns {{artifact: object|null, diagnostics: object[], blocking: boolean}}
+ */
+export function compileRules({ contract, source = null, contractRef = '' }) {
+	const diagnostics = [];
+	const authored = Array.isArray(source?.rules) ? source.rules : [];
+	const operations = contract?.operations ?? {};
+
+	// Ids address a rule in `rules explain` and in every runtime violation report, so a duplicate
+	// makes a violation unattributable. Checked across ALL kinds and operations, once, up front.
+	const seenIds = new Set();
+	for (const rule of authored) {
+		const id = typeof rule?.id === 'string' ? rule.id : '';
+		if (!id) continue;
+		if (seenIds.has(id)) {
+			diagnostics.push(makeRuleDiagnostic('RULE_DUPLICATE_ID', {
+				subject: id,
+				message: `rule id "${id}" is used more than once -- ids must be unique within a feature`,
+				detail: { rule: id },
+			}));
+		}
+		seenIds.add(id);
+	}
+
+	// Contract-projected rules first (R4), so `origin: 'contract'` entries are always present even
+	// when rules.yaml does not exist at all -- pointing at an OpenAPI document is enough to get
+	// real enforcement, with zero authoring.
+	const byOperation = new Map();
+	function bucket(operationId) {
+		if (!byOperation.has(operationId)) byOperation.set(operationId, { field: [], cross: [], transition: [] });
+		return byOperation.get(operationId);
+	}
+	for (const [operationId, opContract] of Object.entries(operations).sort(([a], [b]) => a.localeCompare(b))) {
+		const projected = projectContractRules(operationId, opContract);
+		diagnostics.push(...projected.diagnostics);
+		if (projected.rules.length > 0) bucket(operationId).field.push(...projected.rules);
+	}
+
+	const derivedCompiled = [];
+	for (const rule of authored) {
+		const id = typeof rule?.id === 'string' ? rule.id : '';
+		const kind = rule?.kind;
+		if (!ALL_RULE_KINDS.includes(kind)) {
+			diagnostics.push(makeRuleDiagnostic('RULE_UNKNOWN_KIND', {
+				subject: id || '(unnamed rule)',
+				message: `rule "${id || '(unnamed)'}": unknown kind "${kind}" -- known kinds: ${ALL_RULE_KINDS.join(', ')}`,
+				detail: { rule: id, kind: kind ?? null, known: [...ALL_RULE_KINDS] },
+			}));
+			continue;
+		}
+		// `derived` is resource-scoped, not operation-scoped (R5) -- it has no `operation` field
+		// to resolve against the contract at all, so it is compiled on its own path entirely.
+		if (kind === 'derived') {
+			const { compiled, error } = compileDerivedRule(rule);
+			if (error) { diagnostics.push(error); continue; }
+			derivedCompiled.push(compiled);
+			continue;
+		}
+		const opContract = operations[rule.operation];
+		if (!opContract) {
+			diagnostics.push(makeRuleDiagnostic('RULE_UNKNOWN_OPERATION', {
+				subject: id || '(unnamed rule)',
+				message: `rule "${id || '(unnamed)'}": operation "${rule.operation}" is not in this feature's contract -- known operations: ${Object.keys(operations).sort().join(', ') || '(none)'}`,
+				detail: { rule: id, operation: rule.operation ?? null, known: Object.keys(operations).sort() },
+			}));
+			continue;
+		}
+		const { compiled, error } = KIND_COMPILERS[kind](rule, opContract);
+		if (error) { diagnostics.push(error); continue; }
+		bucket(rule.operation)[kind].push(compiled);
+	}
+
+	const blocking = isBlocking(diagnostics);
+	if (blocking) return { artifact: null, diagnostics, blocking };
+
+	// Deterministic ordering everywhere: operations by id, rules by id within each kind. A second
+	// compile of the same inputs must produce a byte-identical artifact (the bar
+	// handles/conformance.mjs already sets for emit, applied here to compilation).
+	const compiledOperations = {};
+	for (const operationId of [...byOperation.keys()].sort((a, b) => a.localeCompare(b))) {
+		const kinds = byOperation.get(operationId);
+		const entry = {};
+		for (const kind of PREDICATE_KINDS) {
+			if (kinds[kind].length === 0) continue;
+			entry[kind] = kinds[kind].slice().sort((a, b) => a.id.localeCompare(b.id));
+		}
+		if (Object.keys(entry).length > 0) compiledOperations[operationId] = entry;
+	}
+
+	return {
+		artifact: {
+			sbf_feature_rules: RULES_SCHEMA_VERSION,
+			feature_id: contract.feature_id,
+			feature_uid: contract.feature_uid,
+			contract_ref: contractRef,
+			operations: compiledOperations,
+			// R5/Phase 3: `derived` compiles to a generated pure function rather than a predicate,
+			// so it is a separate top-level list, sorted by id for the same determinism guarantee
+			// every other rule list already holds.
+			derived: derivedCompiled.slice().sort((a, b) => a.id.localeCompare(b.id)),
+			unsupported: diagnostics
+				.filter((d) => d.severity === 'warn')
+				.map((d) => ({ code: d.code, subject: d.subject, reason: d.message }))
+				.sort((a, b) => `${a.code}${a.subject}`.localeCompare(`${b.code}${b.subject}`)),
+		},
+		diagnostics,
+		blocking: false,
+	};
+}
+
+// Counts by kind/origin, for `rules check`/`rules list` reporting. Pure, so the CLI never
+// re-derives these inline.
+export function summarizeArtifact(artifact) {
+	const summary = { operations: 0, field: 0, cross: 0, transition: 0, derived: 0, fromContract: 0, declared: 0, unsupported: 0 };
+	if (!artifact) return summary;
+	summary.operations = Object.keys(artifact.operations ?? {}).length;
+	summary.derived = (artifact.derived ?? []).length;
+	summary.declared += summary.derived; // every derived rule is origin:"declared" -- no contract-projection equivalent exists for a computed field
+	summary.unsupported = (artifact.unsupported ?? []).length;
+	for (const kinds of Object.values(artifact.operations ?? {})) {
+		for (const kind of PREDICATE_KINDS) {
+			for (const rule of kinds[kind] ?? []) {
+				summary[kind] += 1;
+				if (rule.origin === 'contract') summary.fromContract += 1;
+				else summary.declared += 1;
+			}
+		}
+	}
+	return summary;
+}

package/rules/derived.mjs

@@ -0,0 +1,87 @@
+// D-business-rules (R5/R9, Phase 3): pure, shared rendering for a `derived` rule's compiled expr
+// tree into real source. One function, reused by all three providers, rather than three drifting
+// copies -- possible ONLY because the closed operator set (add/sub/mul/div) happens to share
+// identical infix syntax across Java, Python, and TypeScript when every operand is typed
+// numerically (no operator overloading ambiguity, no language-specific precedence quirks at this
+// grammar's depth). If a future op ever needed different per-language syntax, this is the single
+// place that assumption would break and need splitting -- named here, not discovered by surprise.
+//
+// Validation of an authored expr tree lives in rules/compile.mjs (the "decide semantics once in
+// JS" doctrine every other rule kind already follows) -- this module ONLY renders an
+// already-validated tree. It never throws on a well-formed tree; a malformed one is a compiler
+// bug upstream, not this module's concern to defend against a second time.
+import { DERIVED_OPS } from './vocabulary.mjs';
+
+const OP_SYMBOLS = Object.freeze({ add: '+', sub: '-', mul: '*', div: '/' });
+
+/**
+ * Renders an already-validated expr node as a parenthesized infix expression, e.g.
+ * `((price * quantity) - discount)`. `refName` maps a `{ref}` leaf's name to the exact identifier
+ * to emit -- callers pass a per-language transform (e.g. Java/TS keep the name as-is, Python
+ * might not need one at all since parameter names are already valid Python identifiers by
+ * construction, see collectParams()'s own identifier rule).
+ */
+export function renderExprInfix(node, refName = (name) => name) {
+	if (Object.hasOwn(node, 'ref')) return refName(node.ref);
+	if (Object.hasOwn(node, 'const')) return formatConst(node.const);
+	if (Object.hasOwn(node, 'op') && DERIVED_OPS.includes(node.op)) {
+		const [left, right] = node.args;
+		return `(${renderExprInfix(left, refName)} ${OP_SYMBOLS[node.op]} ${renderExprInfix(right, refName)})`;
+	}
+	// Unreachable for a tree that passed rules/compile.mjs's own validateDerivedExpr() --
+	// deliberately throws rather than emitting silently-wrong source if it somehow is.
+	throw new Error(`renderExprInfix: not a validated expr node: ${JSON.stringify(node)}`);
+}
+
+// A literal that round-trips identically in Java/Python/TypeScript source for every value this
+// grammar's own validateDerivedExpr() ever admits (a finite JS number) -- integers print without a
+// decimal point in all three (matching each language's own int-literal-as-double/float/number
+// promotion), and JS's own Number-to-string conversion already avoids exponential notation for
+// every magnitude a real business-rule constant would plausibly use.
+function formatConst(value) {
+	return String(value);
+}
+
+/**
+ * Walks an already-validated expr tree and returns every distinct `{ref}` name, in first-appearance
+ * (pre-order, left-to-right) order -- this becomes the generated function's own parameter list, so
+ * the order must be deterministic and match how a human reading the source rule would expect
+ * argument order to fall out.
+ */
+export function collectParams(node, seen = new Set(), out = []) {
+	if (Object.hasOwn(node, 'ref')) {
+		if (!seen.has(node.ref)) { seen.add(node.ref); out.push(node.ref); }
+		return out;
+	}
+	if (Object.hasOwn(node, 'const')) return out;
+	if (Object.hasOwn(node, 'op')) {
+		for (const arg of node.args) collectParams(arg, seen, out);
+		return out;
+	}
+	return out;
+}
+
+/**
+ * Groups a compiled `derived[]` list into one entry per resource, each provider emits one file
+ * per group (a `<Resource>Rules` class/module). Resources sorted alphabetically, rules within a
+ * resource sorted by field name -- deterministic and independent of whatever arbitrary order
+ * rule ids happened to sort into (`artifact.derived` is sorted by id, not by field).
+ *
+ * COST, named rather than silently accepted: if two DIFFERENT features both declare a derived
+ * rule for the same resource name, each feature's own `rules emit` regenerates that resource's
+ * WHOLE file from its own view alone -- whichever feature emits last wins, silently dropping the
+ * other feature's methods for that resource. Merging across features would need real cross-
+ * feature provenance tracking this slice does not build (no proven need yet -- the same
+ * measurement-before-infra discipline `D-javascript-express-adapter` already applied elsewhere).
+ * Named here, in every provider's own postEmitNotes, and in DECISIONS.md -- not hidden.
+ */
+export function groupDerivedByResource(derived) {
+	const byResource = new Map();
+	for (const rule of derived) {
+		if (!byResource.has(rule.resource)) byResource.set(rule.resource, []);
+		byResource.get(rule.resource).push(rule);
+	}
+	return [...byResource.entries()]
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([resource, rules]) => [resource, rules.slice().sort((a, b) => a.field.localeCompare(b.field))]);
+}

package/rules/diagnostics.mjs

@@ -0,0 +1,147 @@
+// D-business-rules (R6): the frozen code table for every way `bskel rules check` can reject or
+// downgrade an authored rule. Mirrors contracts/completeness.mjs's own WARNING_CODES shape
+// (a frozen table, severity stamped from the table rather than supplied by the caller, a
+// `{code, subject}` key), on its own axis -- the same call lib/cross-feature-collisions.mjs made
+// when it added a second evaluator rather than widening WARNING_CODES.
+//
+// THE SPLIT THAT MATTERS, and why this table has no waiver machinery unlike its contract sibling:
+// a contract is built from whatever a real scan and a real OpenAPI document happened to contain,
+// so its ERROR warnings describe facts about someone else's repo that a human may legitimately
+// need to acknowledge and move past -- hence `bskel contract waive`. `rules.yaml` is 100%
+// hand-authored by the person running the command. A rule naming an operation that does not
+// exist is not a fact to be waived, it is a typo to be fixed, and offering a waiver for it would
+// let a rule that can never fire sit in the artifact looking like enforcement. So:
+//
+//   severity 'error' -> `rules check` REFUSES (exit BAD_ARGS). Fix the rule; there is no waiver.
+//   severity 'warn'  -> the rule is dropped into the artifact's `unsupported[]` with this code and
+//                       reported, never silently discarded. The remaining rules still compile.
+//
+// Every WARN member is an EXPRESSIVENESS gap (this vocabulary cannot say that), never a
+// correctness gap -- that distinction is the whole reason the two severities exist here.
+export const RULE_SEVERITY = Object.freeze({ ERROR: 'error', WARN: 'warn' });
+
+export const RULE_DIAGNOSTICS = Object.freeze({
+	// ---- ERROR: authored mistakes, refused ----------------------------------------------------
+	RULE_UNKNOWN_OPERATION: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a rule names an operationId that this feature\'s contract does not define',
+	}),
+	RULE_UNKNOWN_POINTER: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a rule names a JSON Pointer that the operation\'s request body schema does not describe',
+	}),
+	RULE_UNKNOWN_ASSERT: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a rule uses an assertion name outside this vocabulary',
+	}),
+	RULE_UNKNOWN_KIND: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		// Deliberately its own code rather than folded into RULE_UNKNOWN_ASSERT: `kind` selects
+		// WHICH vocabulary applies, so a wrong kind and a wrong assertion are different mistakes
+		// with different fixes. Same "never share a code" reasoning contracts/completeness.mjs
+		// used to keep CONTRACT_OPENAPI_DRIFT and CONTRACT_OPENAPI_MISSING_OPERATION apart.
+		summary: 'a rule declares a kind outside {field, cross, transition}',
+	}),
+	RULE_VALUE_TYPE: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a rule\'s `value` is the wrong shape for its assertion (e.g. minLength: "3" instead of 3)',
+	}),
+	RULE_ASSERT_NOT_APPLICABLE: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		// The case this exists for: `minLength` on an integer field. Left uncaught it would compile
+		// into a rule that is simply never true, which reads as "enforced" to anyone auditing the
+		// artifact -- strictly worse than refusing.
+		summary: 'a rule\'s assertion cannot apply to that field\'s declared type',
+	}),
+	RULE_INCOMPARABLE_TYPES: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a cross-field comparison names two fields whose types are not mutually comparable',
+	}),
+	RULE_ARITY: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a cross-field rule names the wrong number of pointers for its assertion',
+	}),
+	RULE_DUPLICATE_ID: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'two rules share the same id -- ids address a rule in `rules explain` and in every violation report, so they must be unique',
+	}),
+	RULE_TRANSITION_NOT_ENUM: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		// A transition guard is an allow-list over a closed set of states. Without an enum in the
+		// contract there is no closed set, so `from`/`to` values cannot be checked for typos --
+		// and a typo'd state name is a guard that silently never fires.
+		summary: 'a transition rule targets a field whose contract schema declares no enum, so its states cannot be verified',
+	}),
+	RULE_TRANSITION_UNKNOWN_STATE: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a transition rule names a state absent from that field\'s declared enum',
+	}),
+	RULE_NO_CONTRACT_SCHEMA: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		// Fail-closed, deliberately. Without a request body schema there is nothing to validate a
+		// pointer against, so every rule on that operation would be accepted blind.
+		summary: 'a rule targets an operation with no projected requestBodySchema -- re-run `bskel contract emit --openapi-file <doc>` so pointers can be verified',
+	}),
+
+	// ---- ERROR: derived-field authoring mistakes (R5/Phase 3), refused --------------------------
+	RULE_DERIVED_MISSING_FIELDS: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a derived rule is missing a resource name, a field name, or an expr',
+	}),
+	RULE_DERIVED_INVALID_EXPR: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a derived rule\'s expr is not a well-formed {op,args}/{ref}/{const} node -- see rules/derived.mjs for the closed grammar',
+	}),
+	RULE_DERIVED_DIVIDE_BY_ZERO: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		// Compile-time-known zero only -- a divisor that is a ref (a real runtime value) is not
+		// this compiler's concern; the generated code divides by whatever the caller passes,
+		// exactly as any ordinary division does.
+		summary: 'a derived rule divides by a compile-time-known literal zero, which would always throw/produce Infinity at runtime',
+	}),
+	RULE_DERIVED_SELF_REFERENCE: Object.freeze({
+		severity: RULE_SEVERITY.ERROR,
+		summary: 'a derived rule\'s expr references its own field as an input, which has no defined value to read',
+	}),
+
+	// ---- WARN: expressiveness gaps, recorded in `unsupported[]` --------------------------------
+	RULE_UNSUPPORTED_CONSTRAINT: Object.freeze({
+		severity: RULE_SEVERITY.WARN,
+		summary: 'a constraint in the contract\'s own schema has no equivalent in this vocabulary and is not enforced',
+	}),
+	RULE_NON_SCALAR_TARGET: Object.freeze({
+		severity: RULE_SEVERITY.WARN,
+		summary: 'a contract constraint sits on a nested/array field this vocabulary only addresses at scalar leaves',
+	}),
+});
+
+export const RULE_DIAGNOSTIC_NAMES = Object.freeze(Object.keys(RULE_DIAGNOSTICS).sort());
+
+export function getRuleDiagnostic(code) {
+	return Object.hasOwn(RULE_DIAGNOSTICS, code) ? RULE_DIAGNOSTICS[code] : null;
+}
+
+export function requireRuleDiagnostic(code) {
+	const spec = getRuleDiagnostic(code);
+	if (!spec) throw new Error(`unknown rule diagnostic "${code}" -- known codes: ${RULE_DIAGNOSTIC_NAMES.join(', ')}`);
+	return spec;
+}
+
+// Severity is stamped FROM the table, never taken from the caller -- contracts/completeness.mjs's
+// makeWarning() established this exact rule, for the exact reason that a caller free to pick a
+// severity can silently downgrade a refusal into a warning.
+export function makeRuleDiagnostic(code, { subject = null, message = '', detail = {} } = {}) {
+	const spec = requireRuleDiagnostic(code);
+	return { code, severity: spec.severity, subject, message, detail };
+}
+
+// The addressing key, code+subject only. Same reasoning as contracts/completeness.mjs's
+// warningKey(): message text gets rephrased over time and anything keyed on it silently stops
+// matching. `subject` here is a rule id or a source pointer -- both stable.
+export function ruleDiagnosticKey(diagnostic) {
+	return `${diagnostic.code}::${diagnostic.subject ?? '*'}`;
+}
+
+export function isBlocking(diagnostics) {
+	return diagnostics.some((d) => d.severity === RULE_SEVERITY.ERROR);
+}