backend-skeleton 1.3.0 → 1.4.0

package/rules/store.mjs

@@ -0,0 +1,141 @@
+// D-business-rules (R1/R2): the I/O boundary for business rules. Paths, reading the hand-authored
+// YAML source, and reading/writing the compiled JSON artifact with schema validation on BOTH
+// sides -- the exact shape lib/cross-feature-collisions.mjs's
+// loadCrossFeatureResolution/saveCrossFeatureResolution and contracts/completeness.mjs's
+// loadResolution/saveResolution already hold ("refusing to write an invalid ...").
+//
+// rules/compile.mjs stays pure and filesystem-free; everything that touches disk lives here.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { specPath } from '../lib/paths.mjs';
+import { readJsonIfExists, writeFileAtomic } from '../lib/fsutil.mjs';
+import { validateAgainstSchema, formatSchemaErrors } from '../lib/schema-validate.mjs';
+import { RULES_SOURCE_SCHEMA } from './compile.mjs';
+
+// The hand-authored file. Sits directly in the feature's spec dir alongside dependencies.json --
+// both are human-authored declarations about this feature's own fields, so they are siblings.
+export function rulesSourcePath(root, featureId) {
+	return specPath(root, featureId, 'rules.yaml');
+}
+
+// The compiled artifact. In its own `rules/` subdirectory, matching how `handles/migration.sql`
+// already nests a generated artifact under the feature's spec dir.
+export function rulesArtifactPath(root, featureId) {
+	return specPath(root, featureId, 'rules', `${featureId}.rules.json`);
+}
+
+/**
+ * Reads and parses specs/<featureId>/rules.yaml. Returns null when the file does not exist at all
+ * -- a legal, common state meaning "this feature declares no hand-authored rules", which still
+ * compiles to a real artifact from contract-projected rules alone (R4).
+ *
+ * Throws on malformed YAML or a wrong/missing `schema` key. Deliberately NOT schema-validated
+ * beyond that: rules/compile.mjs resolves every rule against the contract itself and produces
+ * strictly better refusals (naming real known fields, real declared types, real enum states) than
+ * a structural schema could -- see schemas/feature-rules.schema.json's own description.
+ */
+export function loadRulesSource(root, featureId) {
+	const file = rulesSourcePath(root, featureId);
+	if (!fs.existsSync(file)) return null;
+	let parsed;
+	try {
+		parsed = parseYaml(fs.readFileSync(file, 'utf8'));
+	} catch (err) {
+		throw new Error(`${file}: not valid YAML -- ${err.message}`);
+	}
+	if (parsed === null || parsed === undefined) return { schema: RULES_SOURCE_SCHEMA, rules: [] };
+	if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+		throw new Error(`${file}: must be a YAML mapping with a "rules:" list, got ${Array.isArray(parsed) ? 'a list' : typeof parsed}`);
+	}
+	if (parsed.schema !== RULES_SOURCE_SCHEMA) {
+		throw new Error(`${file}: expected \`schema: ${RULES_SOURCE_SCHEMA}\` at the top of the file, got ${parsed.schema === undefined ? '(nothing)' : JSON.stringify(parsed.schema)}`);
+	}
+	if (parsed.rules !== undefined && !Array.isArray(parsed.rules)) {
+		throw new Error(`${file}: "rules" must be a list, got ${typeof parsed.rules}`);
+	}
+	return { schema: parsed.schema, rules: parsed.rules ?? [] };
+}
+
+export function loadRulesArtifact(root, featureId) {
+	const file = rulesArtifactPath(root, featureId);
+	const parsed = readJsonIfExists(file);
+	if (parsed === null) return null;
+	const { ok, errors } = validateAgainstSchema('feature-rules.schema.json', parsed);
+	if (!ok) {
+		throw new Error(`${file}: does not match schemas/feature-rules.schema.json:\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	return parsed;
+}
+
+export function saveRulesArtifact(root, featureId, artifact) {
+	const { ok, errors } = validateAgainstSchema('feature-rules.schema.json', artifact);
+	if (!ok) {
+		throw new Error(`refusing to write an invalid rules artifact for "${featureId}":\n${formatSchemaErrors(errors).join('\n')}`);
+	}
+	const file = rulesArtifactPath(root, featureId);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	// Tab-indented + trailing newline, matching every other generated JSON artifact in this repo
+	// (observe's own <feature>.observed-schema.json uses exactly this). Byte-stable across runs so
+	// a no-op recompile leaves the file untouched and the `rules` gate stays green.
+	writeFileAtomic(file, `${JSON.stringify(artifact, null, '\t')}\n`);
+	return artifact;
+}
+
+// A starter rules.yaml, written only when the user explicitly asks for one and only when no file
+// exists. Deliberately contains ZERO real rules -- every example is commented out. Writing a live
+// rule here would be `bskel` inventing a constraint about the user's domain, exactly the line
+// D-greenfield-parameters draws ("does the generated file encode a claim about the user's domain
+// that the user did not state?").
+export function starterRulesSource(featureId) {
+	return `# Business rules for ${featureId}.
+#
+# Compiled by \`bskel rules check --feature ${featureId}\` into
+# specs/${featureId}/rules/${featureId}.rules.json, which is what the generated
+# runtime checkers actually execute. Nothing here is enforced until you run that command.
+#
+# Constraints your OpenAPI document already states (minLength, maximum, enum, ...) are picked up
+# AUTOMATICALLY from the contract -- you do not need to repeat them here. This file is only for
+# the rules no schema keyword can express.
+schema: ${RULES_SOURCE_SCHEMA}
+rules: []
+#
+# Uncomment and adapt any of these -- then run \`bskel rules check --feature ${featureId}\`, which
+# verifies every pointer, type, and enum state against your own contract before compiling.
+#
+#  - id: end-after-start
+#    kind: cross
+#    operation: createBooking
+#    pointers: [/startDate, /endDate]
+#    assert: lt
+#    reason: "a booking cannot end before it starts"
+#
+#  - id: publish-flow
+#    kind: transition
+#    operation: updateArticle
+#    pointer: /status
+#    from: [draft]
+#    to: [published, archived]
+#    reason: "an article may only be published or archived out of draft"
+#
+#  - id: discount-cap
+#    kind: field
+#    operation: createOrder
+#    pointer: /discountPercent
+#    assert: maximum
+#    value: 50
+#    reason: "policy cap, not expressible in the public API schema"
+#
+#  - id: order-total
+#    kind: derived
+#    resource: Order
+#    field: total
+#    expr:
+#      op: sub
+#      args:
+#        - op: mul
+#          args: [{ ref: price }, { ref: quantity }]
+#        - { ref: discount }
+#    reason: "total = price * quantity - discount; compiles to a real Order Rules pure function"
+`;
+}

package/rules/vocabulary.mjs

@@ -0,0 +1,172 @@
+// D-business-rules (R3): the closed vocabulary of business-rule assertions this project compiles
+// into target-language code. Frozen, small, and every member mechanically executable in Java,
+// Python, and TypeScript without interpretation -- that constraint is the whole design, not a
+// convenience. See DECISIONS.md's D-business-rules, R3.
+//
+// This module is PURE DATA plus pure predicates over it. It imports nothing, so it can be read by
+// the compiler, the CLI, and every provider emitter without any risk of the import cycle
+// D-zero-config-scan hit (adapter -> lib/doctor.mjs -> lib/verify.mjs -> scanners/registry.mjs).
+//
+// DELIBERATE NON-OVERLAP with `handles/observe-schema-projection.mjs`. That module already
+// projects `required`/`type`/`pattern` out of a contract's own requestBodySchema, and every
+// provider's generated checker already enforces those three. This vocabulary covers exactly the
+// constraints that projection DROPS -- so a single violation is never reported twice by two
+// different checkers, and neither module has to know what the other kept. `required` as an
+// unconditional assertion is therefore deliberately absent here: it is the contract's/OpenAPI
+// document's own statement, not a business rule layered on top. Its genuinely-new sibling,
+// `requiredIf` (conditional on another field), IS here, because no schema keyword expresses it.
+
+// ---- field assertions: one scalar JSON Pointer, one bounded comparison ----------------------
+//
+// `valueType` is what the rule's own `value` must be (validated at compile time, so a generated
+// runtime never has to defend against a malformed rule). `appliesTo` is the set of projected
+// scalar types the assertion is meaningful against -- checked against the contract's own
+// requestBodySchema at compile time (R6), which is how a rule that says "minLength on an integer"
+// is refused with the real type named instead of silently never firing.
+export const FIELD_ASSERTS = Object.freeze({
+	minLength:        Object.freeze({ valueType: 'integer', appliesTo: Object.freeze(['string']), summary: 'string length >= value' }),
+	maxLength:        Object.freeze({ valueType: 'integer', appliesTo: Object.freeze(['string']), summary: 'string length <= value' }),
+	minimum:          Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number >= value' }),
+	maximum:          Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number <= value' }),
+	exclusiveMinimum: Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number > value' }),
+	exclusiveMaximum: Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number < value' }),
+	multipleOf:       Object.freeze({ valueType: 'number',  appliesTo: Object.freeze(['number', 'integer']), summary: 'number is an exact multiple of value' }),
+	enum:             Object.freeze({ valueType: 'array',   appliesTo: Object.freeze(['string', 'number', 'integer', 'boolean']), summary: 'value is one of a fixed list' }),
+});
+
+// ---- cross-field assertions: two or more pointers, compared to each other -------------------
+//
+// `arity: 2` means exactly two pointers; `arity: 'n'` means two or more. `comparison: true` marks
+// the members whose operands must be mutually comparable (both numeric, or both string) -- a
+// `lt` between a string and an integer is refused at compile time rather than given some
+// language-specific coercion behavior that would differ across the three runtimes.
+export const CROSS_ASSERTS = Object.freeze({
+	lt:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first < second' }),
+	lte:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first <= second' }),
+	gt:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first > second' }),
+	gte:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first >= second' }),
+	eq:                Object.freeze({ arity: 2,   comparison: true,  summary: 'first == second' }),
+	neq:               Object.freeze({ arity: 2,   comparison: true,  summary: 'first != second' }),
+	requiredIf:        Object.freeze({ arity: 2,   comparison: false, summary: 'if the first is present, the second must be too' }),
+	mutuallyExclusive: Object.freeze({ arity: 'n', comparison: false, summary: 'at most one of these may be present' }),
+});
+
+// ---- the three predicate rule kinds -----------------------------------------------------------
+//
+// `derived` is deliberately NOT here: it produces a value rather than answering true/false about
+// one, so it cannot be executed by a predicate checker at all and takes a different compilation
+// path entirely (R5). Keeping the predicate kinds in their own frozen list is what lets the
+// compiler and every checker iterate them generically.
+export const PREDICATE_KINDS = Object.freeze(['field', 'cross', 'transition']);
+
+// Every kind an authored rule may declare -- PREDICATE_KINDS plus `derived`. Used only at the
+// "is this kind even real" dispatch point in rules/compile.mjs; every other consumer (the
+// checkers, `rules explain`'s search) still branches on PREDICATE_KINDS vs. `derived` separately,
+// because the two are executed through genuinely different mechanisms (R5).
+export const ALL_RULE_KINDS = Object.freeze([...PREDICATE_KINDS, 'derived']);
+
+// R5/Phase 3: the closed arithmetic vocabulary a `derived` rule's expr tree may use. Deliberately
+// tiny and binary-only (exactly 2 args per op) -- the explicit "no arbitrary arithmetic beyond the
+// frozen operator set" scope boundary this item's own plan named. A third operand is expressed by
+// nesting (`mul(mul(a,b),c)`), never by widening arity.
+export const DERIVED_OPS = Object.freeze(['add', 'sub', 'mul', 'div']);
+
+// PascalCase for Java/TypeScript method names (`computeTotal`), snake_case for Python
+// (`compute_total`) -- pure string transforms, reused by all three provider emitters so a
+// resource/field name is capitalized identically everywhere rather than three subtly different
+// regexes drifting apart.
+export function pascalCase(name) {
+	return String(name).replace(/(^\w|[-_]\w)/g, (m) => m.replace(/[-_]/, '').toUpperCase());
+}
+
+export function snakeCase(name) {
+	return String(name)
+		.replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+		.replace(/[-\s]+/g, '_')
+		.toLowerCase();
+}
+
+// Where a compiled rule came from. `contract` = projected from the feature's own
+// requestBodySchema, i.e. a fact the user's OpenAPI document already asserts, transported (R4 --
+// the same "copying is not synthesizing" posture D-openapi-passthrough established). `declared` =
+// a human wrote it in rules.yaml. Kept distinct in the compiled artifact so an auditor can always
+// tell which constraints the document licensed and which a human added on top.
+export const RULE_ORIGINS = Object.freeze(['contract', 'declared']);
+
+// The scalar types a rule can address, matching observe-schema-projection.mjs's own SCALAR_TYPES
+// exactly -- a rule can only constrain something that module already projects as a scalar leaf.
+export const RULE_SCALAR_TYPES = Object.freeze(['string', 'number', 'integer', 'boolean']);
+
+export const FIELD_ASSERT_NAMES = Object.freeze(Object.keys(FIELD_ASSERTS).sort());
+export const CROSS_ASSERT_NAMES = Object.freeze(Object.keys(CROSS_ASSERTS).sort());
+
+export function getFieldAssert(name) {
+	return Object.hasOwn(FIELD_ASSERTS, name) ? FIELD_ASSERTS[name] : null;
+}
+
+export function getCrossAssert(name) {
+	return Object.hasOwn(CROSS_ASSERTS, name) ? CROSS_ASSERTS[name] : null;
+}
+
+// The typo-defense points, same shape as lib/gate-definitions.mjs's requireGateDefinition() and
+// contracts/completeness.mjs's requireWarningCode(): name the known values rather than letting a
+// misspelled assertion silently compile to a rule that can never fire.
+export function requireFieldAssert(name) {
+	const spec = getFieldAssert(name);
+	if (!spec) throw new Error(`unknown field assertion "${name}" -- known field assertions: ${FIELD_ASSERT_NAMES.join(', ')}`);
+	return spec;
+}
+
+export function requireCrossAssert(name) {
+	const spec = getCrossAssert(name);
+	if (!spec) throw new Error(`unknown cross-field assertion "${name}" -- known cross-field assertions: ${CROSS_ASSERT_NAMES.join(', ')}`);
+	return spec;
+}
+
+// Is `value` the right shape for this assertion's declared valueType? Deliberately strict:
+// `integer` rejects 1.5 AND rejects a numeric string, because a rule whose operand needs coercing
+// is a rule whose behavior would differ between Java, Python, and JS.
+export function valueMatchesType(valueType, value) {
+	switch (valueType) {
+		case 'integer': return typeof value === 'number' && Number.isInteger(value);
+		case 'number':  return typeof value === 'number' && Number.isFinite(value);
+		case 'array':   return Array.isArray(value) && value.length > 0;
+		case 'none':    return value === undefined;
+		default:        return false;
+	}
+}
+
+// Two projected scalar types are comparable if they are both numeric or both string. Booleans are
+// deliberately never comparable with `lt`/`gt` (ordering booleans is a language-specific accident,
+// not a business rule); `eq`/`neq` between two booleans is still refused here for the same reason
+// consistency matters more than convenience -- use a field `enum` assertion instead.
+export function typesAreComparable(a, b) {
+	const numeric = new Set(['number', 'integer']);
+	if (numeric.has(a) && numeric.has(b)) return true;
+	return a === 'string' && b === 'string';
+}
+
+// Renders one compiled rule as a plain-English sentence, for `bskel rules explain`. Pure and
+// exported (rather than built inline in the CLI) so it has a direct unit test, and so the same
+// wording can be reused by any future renderer -- the same call lib/workflow.mjs made when it
+// exported isMutatingCommand() instead of inlining it.
+export function explainRule({ kind, rule }) {
+	if (kind === 'field') {
+		const spec = getFieldAssert(rule.assert);
+		const what = spec ? spec.summary.replace('value', JSON.stringify(rule.value)) : `${rule.assert} ${JSON.stringify(rule.value)}`;
+		return `${rule.pointer} must satisfy: ${what}`;
+	}
+	if (kind === 'cross') {
+		const spec = getCrossAssert(rule.assert);
+		if (rule.assert === 'requiredIf') return `if ${rule.pointers[0]} is present, ${rule.pointers[1]} must be present too`;
+		if (rule.assert === 'mutuallyExclusive') return `at most one of ${rule.pointers.join(', ')} may be present`;
+		return `${rule.pointers[0]} must be ${spec ? spec.summary.replace('first ', '').replace(' second', '') : rule.assert} ${rule.pointers[1]}`;
+	}
+	if (kind === 'transition') {
+		return `${rule.pointer} may only change from {${rule.from.join(', ')}} to {${rule.to.join(', ')}}`;
+	}
+	if (kind === 'derived') {
+		return `${rule.resource}.${rule.field} is computed from (${rule.params.join(', ')}) -- see \`rules/derived.mjs\`'s renderExprInfix() for the exact formula, or the generated <Resource>Rules class itself`;
+	}
+	return `(no explanation available for kind "${kind}")`;
+}

package/schemas/feature-rules.schema.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:feature-rules:1",
+  "title": "backend-skeleton compiled feature business rules",
+  "description": "Validates specs/<feature_id>/rules/<feature_id>.rules.json -- the DETERMINISTIC, COMPILED artifact rules/compile.mjs produces from a feature contract plus an optional hand-authored specs/<feature_id>/rules.yaml. This is the only rules file any provider emitter reads. See D-business-rules in DECISIONS.md. The authored YAML source is deliberately NOT validated by a schema: rules/compile.mjs resolves every rule against the contract's own requestBodySchema and produces far more actionable refusals than a structural schema could (naming the real known fields, the field's real declared type, the real enum states), so a second, weaker structural gate in front of it would only ever produce worse messages for the same input.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sbf_feature_rules", "feature_id", "feature_uid", "contract_ref", "operations", "derived", "unsupported"],
+  "$defs": {
+    "derivedExpr": {
+      "description": "R5/Phase 3's closed expression grammar for a derived field's formula -- exactly one of an op node (binary, add/sub/mul/div only -- rules/vocabulary.mjs's DERIVED_OPS), a `ref` leaf (a named input, becomes a generated function parameter), or a `const` leaf (a compile-time literal). Deliberately not a general expression language: no loops, no function calls, no I/O, no operator beyond this frozen set.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["op", "args"],
+          "properties": {
+            "op": { "enum": ["add", "sub", "mul", "div"] },
+            "args": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/$defs/derivedExpr" } }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ref"],
+          "properties": { "ref": { "type": "string", "minLength": 1 } }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["const"],
+          "properties": { "const": { "type": "number" } }
+        }
+      ]
+    }
+  },
+  "properties": {
+    "sbf_feature_rules": { "const": "1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "feature_uid": { "type": "string", "format": "uuid" },
+    "contract_ref": {
+      "description": "sha256 of the contract file this artifact was compiled against. A rule is only meaningful against the contract whose pointers/types/enums it was verified against, so pairing a compiled artifact with a different contract must be detectable -- the `rules` gate hashes both, and every provider stamps this value into the emitted runtime resource (the same role observe's own contract_ref plays in <feature>.observed-schema.json).",
+      "type": "string"
+    },
+    "operations": {
+      "description": "Predicate rules, keyed by the contract's own operationId. An operation with no rules is absent entirely rather than present-and-empty.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "field": {
+            "description": "Single-pointer constraints. `origin: contract` entries were projected from the operation's own requestBodySchema (facts the user's OpenAPI document already asserts, transported -- see R4); `origin: declared` entries were hand-authored. Deliberately excludes required/type/pattern, which handles/observe-schema-projection.mjs already projects and every generated checker already enforces -- so one violation is never reported twice.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "pointer", "assert", "value", "origin"],
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "pointer": { "type": "string", "pattern": "^/[^/]+$" },
+                "assert": { "enum": ["minLength", "maxLength", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "enum"] },
+                "value": {},
+                "origin": { "enum": ["contract", "declared"] }
+              }
+            }
+          },
+          "cross": {
+            "description": "Multi-pointer constraints. `types` records each pointer's contract-declared scalar type at compile time, so a generated runtime never has to re-derive it -- and so a later contract change that alters a type is visible as a real diff in this artifact.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "pointers", "assert", "types", "origin"],
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "pointers": { "type": "array", "minItems": 2, "items": { "type": "string", "pattern": "^/[^/]+$" } },
+                "assert": { "enum": ["lt", "lte", "gt", "gte", "eq", "neq", "requiredIf", "mutuallyExclusive"] },
+                "types": { "type": "array", "minItems": 2, "items": { "enum": ["string", "number", "integer", "boolean"] } },
+                "origin": { "enum": ["contract", "declared"] }
+              }
+            }
+          },
+          "transition": {
+            "description": "State-transition guards: a literal from[] -> to[] allow-list over one scalar pointer whose contract schema declares an enum. Compilation refuses a transition on a field with no enum, because without a closed state set a typo'd state name becomes a guard that silently never fires.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "pointer", "from", "to", "origin"],
+              "properties": {
+                "id": { "type": "string", "minLength": 1 },
+                "pointer": { "type": "string", "pattern": "^/[^/]+$" },
+                "from": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+                "to": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+                "origin": { "enum": ["contract", "declared"] }
+              }
+            }
+          }
+        }
+      }
+    },
+    "derived": {
+      "description": "Derived/computed field rules. Unlike the three predicate kinds above, a derived rule PRODUCES a value rather than answering true/false about one, so it cannot be executed by a predicate checker and compiles to a generated pure-function class instead (R5). Resource-scoped, not operation-scoped -- unlike field/cross/transition, a derived rule has no `operation` and is never checked against the contract's requestBodySchema.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "resource", "field", "params", "expr", "origin"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "resource": { "type": "string", "minLength": 1 },
+          "field": { "type": "string", "minLength": 1 },
+          "params": {
+            "description": "Every distinct {ref} name in `expr`, in first-appearance order -- this becomes the generated pure function's own parameter list (rules/derived.mjs's collectParams()).",
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "expr": { "$ref": "#/$defs/derivedExpr" },
+          "origin": { "const": "declared" }
+        }
+      }
+    },
+    "unsupported": {
+      "description": "Every constraint found in the contract that this vocabulary cannot express, recorded rather than silently dropped -- the same honesty mechanism handles/observe-schema-projection.mjs's own `unsupported[]` JSON-Pointer list provides. An auditor reading this artifact can always tell what is NOT enforced.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "subject", "reason"],
+        "properties": {
+          "code": { "type": "string", "pattern": "^RULE_[A-Z_]+$" },
+          "subject": { "type": ["string", "null"] },
+          "reason": { "type": "string" }
+        }
+      }
+    }
+  }
+}