backend-skeleton 1.3.0 → 1.5.0

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" }
+        }
+      }
+    }
+  }
+}