backend-skeleton 1.4.0 → 1.6.0

package/schemas/impact-baseline.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:impact-baseline:1",
+  "title": "backend-skeleton impact surface baseline",
+  "description": "Validates specs/<feature_id>/impact-baseline.json, written only by `bskel impact accept` -- a projection of ONE feature's own public surface at the moment it was last accepted as the reference point for change detection. Git-independent by design (specs/ is commonly gitignored, see D-contract-history's own finding) -- this file itself is the durable record of 'what did this feature's surface look like last time a human/CI accepted it'. Every *_shape_hash is sha256(JSON.stringify(sortKeysDeep(subtree))), the exact canonicalization lib/attest.mjs already implements and is reused unchanged (see D-attestation-payload-completeness's K1). See D-cross-feature-impact-graph.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "captured_at", "surface"],
+  "properties": {
+    "schema": { "const": "sbf.impact-baseline/1" },
+    "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
+    "captured_at": { "type": "string", "format": "date-time" },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["operations", "resources", "fields"],
+      "properties": {
+        "operations": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["verb", "path", "request_shape_hash", "response_shape_hash", "error_shape_hash"],
+            "properties": {
+              "verb": { "type": "string" },
+              "path": { "type": "string" },
+              "request_shape_hash": { "type": ["string", "null"] },
+              "response_shape_hash": { "type": ["string", "null"] },
+              "error_shape_hash": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "resources": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["file_sha256", "table", "table_source"],
+            "properties": {
+              "file_sha256": { "type": ["string", "null"] },
+              "table": { "type": ["string", "null"] },
+              "table_source": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "fields": {
+          "description": "Only fields named by a declared dependencies.json edge -- this project has no per-adapter field enumerator (see D-field-dependency's own EXIT), so a field only exists here where something else already named it. Keyed \"<ResourceType>.<field>\".",
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["source_file_sha256"],
+            "properties": { "source_file_sha256": { "type": ["string", "null"] } }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/impact-graph.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:impact-graph:1",
+  "title": "backend-skeleton cross-feature impact graph",
+  "description": "Validates the return shape of lib/impact-graph.mjs's buildImpactGraph(root) and `bskel impact export --format json`'s output. D-cross-feature-impact-graph. Every node id is an already-persisted exact identity (a feature id, a contract operation key, a scan-report resourceType, a table name, or a declared dependency field) -- there is no inferred/guessed node. Every edge carries `basis` (which artifact, and its sha256, proves this edge exists) and `confidence` ('proven'|'heuristic') so a consumer can tell a name-identity match backed by an explicit @Table/@Column from one backed by an adapter's guessed fallback. Deliberately no `calls` relation and no third confidence value -- service-to-service/dynamic-client inference is out of scope (see DECISIONS.md's EXIT list), and a missing edge is honest while a guessed one is not.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "generated_at", "nodes", "edges"],
+  "properties": {
+    "schema": { "const": "sbf.impact-graph/1" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "type", "label"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "type": { "enum": ["feature", "operation", "resource", "table", "field"] },
+          "label": { "type": "string" },
+          "feature_id": { "type": ["string", "null"] },
+          "file": { "type": ["string", "null"], "description": "Repo-relative source file, when this node resolves to one (resource/field)." },
+          "attrs": { "type": "object", "description": "Type-specific extra facts (verb/path for operation, table/tableSource for resource, etc.) -- open, since node types genuinely carry different metadata." }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["source", "target", "relation", "confidence", "basis"],
+        "properties": {
+          "source": { "type": "string" },
+          "target": { "type": "string" },
+          "relation": { "enum": ["declares_operation", "owns_resource", "maps_to_table", "derives_from", "fk_references", "name_collides_with"] },
+          "confidence": { "enum": ["proven", "heuristic"] },
+          "basis": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["artifact", "artifact_sha256", "locator"],
+            "properties": {
+              "artifact": { "type": "string", "description": "Repo-relative path to the persisted file this edge was read from." },
+              "artifact_sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$" },
+              "locator": { "type": "string", "description": "Where inside the artifact, e.g. a JSON pointer or field name -- human-navigable, not machine-parsed." }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/impact-report.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:impact-report:1",
+  "title": "backend-skeleton impact check report",
+  "description": "Validates specs/<feature_id>/impact-report.json, written by `bskel impact check` -- READ-mostly: diffs the current surface against impact-baseline.json and walks the impact graph, but never advances the baseline itself (only `bskel impact accept` does that). `unknowns` follows cross-feature-report.schema.json's own 'detect and warn, never silently omit' posture verbatim. See D-cross-feature-impact-graph.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "generated_at", "baseline", "changes", "outbound", "inbound", "unknowns"],
+  "properties": {
+    "schema": { "const": "sbf.impact-report/1" },
+    "feature_id": { "type": "string" },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "baseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["present"],
+      "properties": {
+        "present": { "type": "boolean" },
+        "captured_at": { "type": ["string", "null"] }
+      }
+    },
+    "changes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["change_key", "kind", "subject"],
+        "properties": {
+          "change_key": { "type": "string", "description": "\"<kind>:<subject>:<new_hash_12>\" -- embeds the NEW hash, so a disposition recorded for one shape can never cover a later, different change to the same subject." },
+          "kind": {
+            "enum": [
+              "operation_added", "operation_removed", "operation_verb_changed", "operation_path_changed",
+              "operation_request_shape_changed", "operation_response_shape_changed", "operation_error_shape_changed",
+              "resource_removed", "resource_table_changed", "field_source_moved"
+            ]
+          },
+          "subject": { "type": "string" },
+          "from": {},
+          "to": {}
+        }
+      }
+    },
+    "outbound": {
+      "description": "Impact THIS feature's changes have on other, downstream features -- what `bskel impact accept` blocks on when confidence is 'proven'.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["change_key", "downstream_feature", "via", "confidence", "disposition"],
+        "properties": {
+          "change_key": { "type": "string" },
+          "downstream_feature": { "type": "string" },
+          "via": { "enum": ["derives_from", "fk_references", "name_collides_with"] },
+          "basis": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "artifact": { "type": "string" },
+              "artifact_sha256": { "type": ["string", "null"] },
+              "locator": { "type": "string" }
+            }
+          },
+          "confidence": { "enum": ["proven", "heuristic"] },
+          "disposition": { "enum": ["compatible", "migrate", "waive", null] }
+        }
+      }
+    },
+    "inbound": {
+      "description": "Migration obligations another feature's own impact accept recorded AGAINST this feature -- what `bskel impact ack` clears.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["upstream_feature", "change_key", "mode", "tracked_by", "acknowledged"],
+        "properties": {
+          "upstream_feature": { "type": "string" },
+          "change_key": { "type": "string" },
+          "mode": { "const": "migrate" },
+          "tracked_by": { "type": "string" },
+          "acknowledged": { "type": "boolean" }
+        }
+      }
+    },
+    "unknowns": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/impact-resolution.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:impact-resolution:1",
+  "title": "backend-skeleton impact dispositions",
+  "description": "Validates specs/<feature_id>/impact-resolution.json, written by `bskel impact disposition`/`bskel impact ack`. Three modes with three genuinely different mechanical consequences (see D-cross-feature-impact-graph's D6): 'compatible' unblocks one {change_key, downstream_feature} pair and nothing else; 'migrate' requires --tracked-by and creates a two-sided handshake (an inbound obligation on the downstream feature, cleared only by that feature's own `impact ack`); 'waive' requires --expires and decays via the same mechanism D-waiver-expiry already ships for `contract waive`. Keyed by {change_key, downstream_feature} -- never a wildcard, matching cross-feature-resolution.schema.json's own stated discipline.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "feature_id", "dispositions"],
+  "properties": {
+    "schema": { "const": "sbf.impact-resolution/1" },
+    "feature_id": { "type": "string" },
+    "dispositions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["change_key", "downstream_feature", "mode", "reason", "at"],
+        "properties": {
+          "change_key": { "type": "string" },
+          "downstream_feature": { "type": "string" },
+          "mode": { "enum": ["compatible", "migrate", "waive"] },
+          "reason": { "type": "string", "minLength": 1 },
+          "tracked_by": { "type": ["string", "null"], "description": "Required (non-empty) iff mode is 'migrate'." },
+          "expires_at": { "type": ["string", "null"], "format": "date-time", "description": "Required iff mode is 'waive' -- ISO instant this disposition stops covering its change_key." },
+          "acknowledged": { "type": "boolean", "default": false, "description": "Only meaningful for mode 'migrate' -- flipped true by the DOWNSTREAM feature's own `bskel impact ack`." },
+          "acknowledged_at": { "type": ["string", "null"] },
+          "acknowledged_reason": { "type": ["string", "null"] },
+          "at": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

package/schemas/java-source-splice.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sbf:java-source-splice:1",
+  "title": "backend-skeleton java-source-splice request document (--splice-file)",
+  "description": "D-java-source-splice: the input document for `bskel patch propose --kind java-source-splice --splice-file <path>`. A single Java file plus an ordered, closed-vocabulary list of structural edits -- exactly the four operations handles/providers/java-spring/source-splice.mjs's planJavaSourceSplice() knows how to plan. `locator` identifies a member by its language-guaranteed identity (a type's fully-qualified name plus, for a method, its erased parameter types -- the same rule javac itself uses to forbid two same-named same-erased-signature overloads), never by line/column (those are recomputed fresh on every plan, never trusted from this file).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "file", "edits"],
+  "properties": {
+    "schema": { "const": "sbf.java-source-splice/1" },
+    "file": { "type": "string", "minLength": 1, "description": "Repo-relative path to the single Java source file every edit in this document targets." },
+    "edits": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/edit" }
+    }
+  },
+  "$defs": {
+    "locator": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type_fqn", "member_kind", "member_name"],
+      "properties": {
+        "type_fqn": { "type": "string", "minLength": 1, "description": "The single top-level type's fully-qualified name -- V1 refuses a file declaring more than one top-level type." },
+        "member_kind": { "enum": ["method", "field"] },
+        "member_name": { "type": "string", "minLength": 1 },
+        "erased_param_types": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Method locators only -- the exact erased (generics-stripped) fully-qualified parameter types, in order. This is what disambiguates an overload; a field locator omits it entirely."
+        }
+      }
+    },
+    "edit": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["op", "locator", "replacement"],
+          "properties": {
+            "op": { "const": "replace-method-body" },
+            "locator": { "$ref": "#/$defs/locator" },
+            "replacement": { "type": "string", "minLength": 2, "description": "The whole new method body, including the enclosing braces: must start with \"{\" and end with \"}\"." }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["op", "locator", "statements"],
+          "properties": {
+            "op": { "const": "insert-method-body-prologue" },
+            "locator": { "$ref": "#/$defs/locator" },
+            "statements": { "type": "string", "minLength": 1, "description": "Raw statement text to insert at the top of the method body -- the planner derives the actual replacement (original body text is required to survive as a verbatim suffix)." }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["op", "locator", "replacement"],
+          "properties": {
+            "op": { "const": "replace-field-initializer" },
+            "locator": { "$ref": "#/$defs/locator" },
+            "replacement": { "type": "string", "minLength": 1, "description": "The new initializer expression only -- no leading \"=\", no trailing \";\"." }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["op", "imports"],
+          "properties": {
+            "op": { "const": "add-import" },
+            "imports": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 1,
+              "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_.]*$" },
+              "description": "Exactly one fully-qualified import -- at most one add-import edit is permitted per transaction (see the planner's own WHY). No wildcard, no static import."
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/patch-transaction.schema.json

@@ -10,7 +10,7 @@
     "schema": { "const": "sbf.patch-transaction/1" },
     "transaction_id": { "type": "string", "pattern": "^pt-[0-9a-f-]{36}$" },
     "feature_id": { "type": "string", "pattern": "^[0-9]{3}-[a-z0-9]+(-[a-z0-9]+)*$" },
-    "kind": { "enum": ["config-apply", "ddl-apply"] },
+    "kind": { "enum": ["config-apply", "ddl-apply", "java-source-splice"] },
     "source": {
       "type": "object",
       "description": "Kind-specific opaque context needed to re-plan this transaction fresh at approve/apply time. Shape enforced per-kind by the allOf/if-then branches below."
@@ -56,7 +56,11 @@
       "properties": {
         "reason": { "type": "string" },
         "at": { "type": "string", "format": "date-time" },
-        "forced": { "type": "boolean" }
+        "forced": { "type": "boolean" },
+        "compile_after_rollback": {
+          "enum": ["ok", "failed"],
+          "description": "D-java-source-splice: java-source-splice only. Deliberately added HERE, to the base `rollback` object, not inside a per-kind allOf/if-then branch -- `rollback` is additionalProperties:false, and a branch's `then` schema is a SEPARATE schema applied to the same instance, so it cannot widen a sibling schema's own closed property list (confirmed live: a branch-added property is still rejected by the base schema's additionalProperties:false). Optional, not required -- absent on every config-apply/ddl-apply record, and on any java-source-splice record persisted before this field existed."
+        }
       }
     }
   },
@@ -177,6 +181,87 @@
           }
         }
       }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "java-source-splice" } } },
+      "then": {
+        "properties": {
+          "source": {
+            "additionalProperties": false,
+            "required": ["request_file"],
+            "properties": {
+              "request_file": { "type": "string", "description": "The --splice-file path this transaction was originally proposed from -- audit trail only, never re-read at approve/apply time (paramsFromTxn() reconstructs planner params entirely from `target`)." }
+            }
+          },
+          "target": {
+            "additionalProperties": false,
+            "required": ["file", "source_root", "line_terminator", "edits"],
+            "properties": {
+              "file": { "type": "string" },
+              "source_root": { "type": "string" },
+              "line_terminator": { "enum": ["\n", "\r\n"] },
+              "edits": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["op", "region_hash", "signature_hash", "located"],
+                  "properties": {
+                    "op": { "enum": ["replace-method-body", "insert-method-body-prologue", "replace-field-initializer", "add-import"] },
+                    "locator": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["type_fqn", "member_kind", "member_name"],
+                      "properties": {
+                        "type_fqn": { "type": "string" },
+                        "member_kind": { "enum": ["method", "field"] },
+                        "member_name": { "type": "string" },
+                        "erased_param_types": { "type": "array", "items": { "type": "string" } }
+                      }
+                    },
+                    "replacement": { "type": "string" },
+                    "statements": { "type": "string" },
+                    "imports": { "type": "array", "items": { "type": "string" } },
+                    "region_hash": { "type": "string" },
+                    "signature_hash": { "type": ["string", "null"] },
+                    "located": {
+                      "type": "object",
+                      "additionalProperties": false,
+                      "required": ["start", "end", "begin_line", "end_line"],
+                      "description": "A cache of where this edit's region was found at the time of the last plan -- NEVER authoritative (re-derived fresh from `locator` on every plan; a mismatch with the current file just means something else moved, not an error).",
+                      "properties": {
+                        "start": { "type": "integer" },
+                        "end": { "type": "integer" },
+                        "begin_line": { "type": ["integer", "null"] },
+                        "end_line": { "type": ["integer", "null"] }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "postcondition": {
+            "additionalProperties": false,
+            "required": ["kind", "build_tool", "build_command"],
+            "properties": {
+              "kind": { "const": "java-compiles" },
+              "build_tool": { "type": "string" },
+              "build_command": { "type": "string" }
+            }
+          },
+          "apply": {
+            "additionalProperties": false,
+            "required": ["at", "postimage_file_hash", "build_tool"],
+            "properties": {
+              "at": { "type": "string", "format": "date-time" },
+              "postimage_file_hash": { "type": "string" },
+              "build_tool": { "type": "string" }
+            }
+          }
+        }
+      }
     }
   ]
 }