backend-skeleton 1.6.0 → 1.7.1

package/schemas/decision-event.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:decision-event:1",
+  "title": "backend-skeleton decision event",
+  "description": "D-decision-event-log: one line of a .sbf/<feature_id>.decisions.jsonl file, appended by lib/decision-log.mjs's appendDecisionEvent() every time one of the four spec-side decision files (contract-resolution, cross-feature-resolution, impact-resolution, patch-approvals) is written -- mirrors gate-event.schema.json's own shape and resilience contract exactly (append-only JSONL, a corrupt/invalid line is skipped with a warning at read time, never a hard failure). Deliberately NOT a unified record type across the four decision files themselves -- their on-disk shapes stay exactly as they were (different upsert semantics: contract waivers are append-if-absent, impact dispositions are replace-by-key, and forcing either into the other would be the over-unification this design explicitly rejected). `subject` is a discriminated union keyed on `kind`, carrying that decision kind's REAL key object verbatim -- never flattened to a string -- because a generic string key is exactly how the anti-wildcard property every one of the four already enforces (a decision covers ONE exact subject, never a class of future subjects) would eventually erode. This log is machine-local (.sbf/ is gitignored-by-convention) and is NOT tamper-evident on its own; its evidentiary value comes from being rolled up into a SIGNED gate-export attestation (see D-attestation-payload-completeness), exactly as gates.*.history already is.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "kind", "action", "at", "reason", "feature_id", "subject"],
+  "properties": {
+    "schema": { "const": "sbf.decision-event/1" },
+    "kind": { "enum": ["contract_waiver", "cross_feature_waiver", "impact_disposition", "patch_approval"] },
+    "action": { "enum": ["record", "renew", "withdraw", "acknowledge"] },
+    "at": { "type": "string", "format": "date-time" },
+    "reason": { "type": "string", "minLength": 1 },
+    "feature_id": { "type": "string" },
+    "subject": {
+      "description": "The exact key object for this decision, shaped per `kind` -- never a flattened string.",
+      "oneOf": [
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["code", "subject"],
+          "properties": { "code": { "type": "string" }, "subject": { "type": ["string", "null"] } }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["signal", "identifier", "other_feature"],
+          "properties": { "signal": { "type": "string" }, "identifier": { "type": "string" }, "other_feature": { "type": "string" } }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["change_key", "downstream_feature"],
+          "properties": { "change_key": { "type": "string" }, "downstream_feature": { "type": "string" } }
+        },
+        {
+          "type": "object", "additionalProperties": false,
+          "required": ["resource", "field"],
+          "properties": { "resource": { "type": "string" }, "field": { "type": "string" } }
+        }
+      ]
+    },
+    "mode": { "type": ["string", "null"] },
+    "expires_at": { "type": ["string", "null"] },
+    "tracked_by": { "type": ["string", "null"] },
+    "strategy": { "type": ["string", "null"] }
+  }
+}

package/schemas/gate-export.schema.json

@@ -18,7 +18,7 @@
   ],
   "properties": {
     "schema": {
-      "const": "sbf.gate-export/3"
+      "const": "sbf.gate-export/4"
     },
     "feature_id": {
       "type": "string",
@@ -151,7 +151,8 @@
         "stack_record_hash",
         "impact_baseline_hash",
         "impact_report_hash",
-        "impact_resolution_hash"
+        "impact_resolution_hash",
+        "patch_approvals_hash"
       ],
       "properties": {
         "scan_report_hash": {
@@ -265,6 +266,13 @@
             "null"
           ],
           "pattern": "^[0-9a-f]{64}$"
+        },
+        "patch_approvals_hash": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[0-9a-f]{64}$"
         }
       }
     },
@@ -411,9 +419,11 @@
       "required": [
         "forced",
         "revoked",
-        "waiver_files"
+        "waiver_files",
+        "records",
+        "event_counts"
       ],
-      "description": "D-attestation-payload-completeness (K2): rolled up purely from the gate records already in `gates` above -- zero new file reads.",
+      "description": "D-attestation-payload-completeness (K2): forced/revoked rolled up purely from the gate records already in `gates` above -- zero new file reads. D-decision-event-log (D7) additive, sbf.gate-export/3 -> /4: `records`/`event_counts` cover the four spec-side decision files (contract waivers, cross-feature waivers, impact dispositions, patch approvals) -- a /3 attestation still verifies (K7's own promise), it just won't have these two keys.",
       "properties": {
         "forced": {
           "type": "array",
@@ -486,49 +496,104 @@
           "additionalProperties": false,
           "required": [
             "contract_resolution",
-            "cross_feature_resolution"
+            "cross_feature_resolution",
+            "impact_resolution",
+            "patch_approvals"
           ],
-          "description": "presence + hash only -- the CONTENT is already bound via `artifacts` above (contract_resolution_hash / cross_feature_resolution_hash), never embedded here a second time.",
+          "description": "presence + hash only -- the CONTENT is already bound via `artifacts` above, and again (live-evaluated) via `records` below, never embedded here a second time.",
           "properties": {
-            "contract_resolution": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": [
-                "present",
-                "hash"
-              ],
-              "properties": {
-                "present": {
-                  "type": "boolean"
-                },
-                "hash": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
+            "contract_resolution": { "$ref": "#/$defs/waiverFileRef" },
+            "cross_feature_resolution": { "$ref": "#/$defs/waiverFileRef" },
+            "impact_resolution": { "$ref": "#/$defs/waiverFileRef" },
+            "patch_approvals": { "$ref": "#/$defs/waiverFileRef" }
+          }
+        },
+        "records": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "contract_waivers",
+            "cross_feature_waivers",
+            "impact_dispositions",
+            "patch_approvals"
+          ],
+          "description": "D-decision-event-log (D7): LIVE-evaluated entries only (expired contract/impact entries excluded, mirroring gates.*.live's current-vs-live split) -- never the raw stored array, so an expired-but-not-yet-renewed waiver never reads as still covering its warning inside a signed attestation.",
+          "properties": {
+            "contract_waivers": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["code", "subject", "reason", "at", "expires_at"],
+                "properties": {
+                  "code": { "type": "string" },
+                  "subject": { "type": ["string", "null"] },
+                  "reason": { "type": "string" },
+                  "at": { "type": "string" },
+                  "expires_at": { "type": ["string", "null"] }
                 }
               }
             },
-            "cross_feature_resolution": {
-              "type": "object",
-              "additionalProperties": false,
-              "required": [
-                "present",
-                "hash"
-              ],
-              "properties": {
-                "present": {
-                  "type": "boolean"
-                },
-                "hash": {
-                  "type": [
-                    "string",
-                    "null"
-                  ]
+            "cross_feature_waivers": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["signal", "identifier", "other_feature", "reason", "at"],
+                "properties": {
+                  "signal": { "type": "string" },
+                  "identifier": { "type": "string" },
+                  "other_feature": { "type": "string" },
+                  "reason": { "type": "string" },
+                  "at": { "type": "string" }
+                }
+              }
+            },
+            "impact_dispositions": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["change_key", "downstream_feature", "mode", "reason", "tracked_by", "expires_at", "acknowledged"],
+                "properties": {
+                  "change_key": { "type": "string" },
+                  "downstream_feature": { "type": "string" },
+                  "mode": { "type": "string" },
+                  "reason": { "type": "string" },
+                  "tracked_by": { "type": ["string", "null"] },
+                  "expires_at": { "type": ["string", "null"] },
+                  "acknowledged": { "type": "boolean" }
+                }
+              }
+            },
+            "patch_approvals": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["resource", "field", "strategy", "reason", "at"],
+                "properties": {
+                  "resource": { "type": "string" },
+                  "field": { "type": "string" },
+                  "strategy": { "type": "string" },
+                  "reason": { "type": "string" },
+                  "at": { "type": "string" }
                 }
               }
             }
           }
+        },
+        "event_counts": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["contract_waiver", "cross_feature_waiver", "impact_disposition", "patch_approval"],
+          "description": "total decision-log events per kind (all actions combined) -- an all-zero count is informative (no log file, or no events of this kind), distinct from the file not existing at all.",
+          "properties": {
+            "contract_waiver": { "type": "integer", "minimum": 0 },
+            "cross_feature_waiver": { "type": "integer", "minimum": 0 },
+            "impact_disposition": { "type": "integer", "minimum": 0 },
+            "patch_approval": { "type": "integer", "minimum": 0 }
+          }
         }
       }
     },
@@ -562,5 +627,16 @@
         }
       }
     }
+  },
+  "$defs": {
+    "waiverFileRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["present", "hash"],
+      "properties": {
+        "present": { "type": "boolean" },
+        "hash": { "type": ["string", "null"] }
+      }
+    }
   }
 }