gentle-pi 1.2.0 → 2.0.0

package/contracts/review-integration/v1/schemas/failure.schema.json

@@ -22,7 +22,7 @@
     "schema": {"const": "gentle-ai.review-integration.failure/v1"},
     "contract": {"const": "gentle-ai.review-integration/v1"},
     "operation": {
-      "enum": ["review.capabilities", "review.start", "review.status", "review.finalize", "review.validate", "review.bind_sdd"]
+      "enum": ["review.capabilities", "review.start", "review.status", "review.finalize", "review.repair", "review.retry_final_verification", "review.validate", "review.bind_sdd"]
     },
     "phase": {"enum": ["preflight", "pre_native", "native_running", "native_committed", "reconciliation"]},
     "code": {"type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$"},
@@ -33,6 +33,7 @@
     "replayability": {"enum": ["not_replayable", "exact_replay_safe", "status_required", "manual_action_required"]},
     "lineage_id": {"type": "string", "maxLength": 128, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
     "request_digest": {"$ref": "#/$defs/sha256"},
+    "progress_identity": {"$ref": "#/$defs/sha256"},
     "required_inputs": {
       "type": "array",
       "uniqueItems": true,
@@ -46,14 +47,42 @@
           "successor_lineage_id",
           "disposition",
           "reason",
-          "actor"
+          "actor",
+          "incident",
+          "maintainer_authorization",
+          "base_ref"
         ]
       }
     },
-    "next_action": {"enum": ["correct_request", "retry", "retry_with_bounded_backoff", "review.status", "review.finalize", "review.bind_sdd", "explicit-maintainer-action", "stop"]},
+    "next_action": {"enum": ["correct_request", "retry", "retry_with_bounded_backoff", "review.status", "review.finalize", "review.repair", "review.bind_sdd", "explicit-maintainer-action", "stop"]},
     "cause_category": {"enum": ["inventory_io_or_layout", "lock_ambiguous", "reset_residue", "record_or_graph_invalid", "inventory_incomplete"]},
+    "cause": {"type": "string", "minLength": 1, "maxLength": 4000, "pattern": "^[^\\r\\n]+$"},
     "context": {"$ref": "#/$defs/gate_context"}
   },
+  "allOf": [
+    {
+      "if": {
+        "required": ["progress_identity"]
+      },
+      "then": {
+        "required": ["lineage_id", "request_digest"],
+        "properties": {
+          "operation": {"const": "review.repair"}
+        }
+      }
+    },
+    {
+      "if": {
+        "required": ["request_digest"],
+        "properties": {
+          "operation": {"const": "review.repair"}
+        }
+      },
+      "then": {
+        "required": ["progress_identity"]
+      }
+    }
+  ],
   "$defs": {
     "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
     "tree": {"type": "string", "pattern": "^[0-9a-f]{40}(?:[0-9a-f]{24})?$"},
@@ -103,15 +132,32 @@
         }
       }
     },
-    "gate_context": {
+    "optional_sha256": {
+      "anyOf": [
+        {"const": ""},
+        {"$ref": "#/$defs/sha256"}
+      ]
+    },
+    "binding_revision": {
       "type": "object",
       "additionalProperties": false,
-      "required": [
-        "scope_change"
-      ],
+      "required": ["expected", "current"],
       "properties": {
-        "scope_change": {"$ref": "#/$defs/scope_change"}
+        "expected": {"$ref": "#/$defs/optional_sha256"},
+        "current": {"$ref": "#/$defs/optional_sha256"}
       }
+    },
+    "gate_context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "scope_change": {"$ref": "#/$defs/scope_change"},
+        "binding_revision": {"$ref": "#/$defs/binding_revision"}
+      },
+      "oneOf": [
+        {"required": ["scope_change"]},
+        {"required": ["binding_revision"]}
+      ]
     }
   }
 }

package/contracts/review-integration/v1/schemas/final-verification-incident.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/final-verification-incident.schema.json",
+  "title": "Gentle AI final-verification tooling incident",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "class",
+    "lineage_id",
+    "terminal_revision",
+    "validating_revision",
+    "target_identity",
+    "failed_evidence_hash",
+    "finalize_request_digest"
+  ],
+  "properties": {
+    "schema": {
+      "const": "gentle-ai.review-final-verification-incident/v1"
+    },
+    "class": {
+      "const": "procedural_tooling_failure"
+    },
+    "lineage_id": {
+      "type": "string",
+      "maxLength": 128,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "terminal_revision": {
+      "$ref": "#/$defs/sha256"
+    },
+    "validating_revision": {
+      "$ref": "#/$defs/sha256"
+    },
+    "target_identity": {
+      "$ref": "#/$defs/sha256"
+    },
+    "failed_evidence_hash": {
+      "$ref": "#/$defs/sha256"
+    },
+    "finalize_request_digest": {
+      "$ref": "#/$defs/sha256"
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}

package/contracts/review-integration/v1/schemas/operation.schema.json

@@ -4,16 +4,41 @@
   "title": "Gentle AI negotiated review operation result",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schema", "contract", "operation", "result"],
+  "required": [
+    "schema",
+    "contract",
+    "operation",
+    "result"
+  ],
   "properties": {
-    "schema": {"const": "gentle-ai.review-integration.operation/v1"},
-    "contract": {"const": "gentle-ai.review-integration/v1"},
-    "operation": {"enum": ["review.finalize", "review.validate", "review.bind_sdd"]},
+    "schema": {
+      "const": "gentle-ai.review-integration.operation/v1"
+    },
+    "contract": {
+      "const": "gentle-ai.review-integration/v1"
+    },
+    "operation": {
+      "enum": [
+        "review.finalize",
+        "review.validate",
+        "review.bind_sdd",
+        "review.retry_final_verification"
+      ]
+    },
     "result": {
       "oneOf": [
-        {"$ref": "#/$defs/finalize"},
-        {"$ref": "#/$defs/validate"},
-        {"$ref": "#/$defs/bind_sdd"}
+        {
+          "$ref": "#/$defs/finalize"
+        },
+        {
+          "$ref": "#/$defs/validate"
+        },
+        {
+          "$ref": "#/$defs/bind_sdd"
+        },
+        {
+          "$ref": "#/$defs/retry_final_verification"
+        }
       ]
     }
   },
@@ -25,42 +50,190 @@
     "finalize": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["operation", "lineage_id", "state", "action", "store_revision"],
+      "required": [
+        "operation",
+        "lineage_id",
+        "state",
+        "action",
+        "store_revision"
+      ],
       "properties": {
-        "operation": {"const": "review/finalize"},
-        "lineage_id": {"type": "string", "minLength": 1},
-        "state": {"type": "string", "minLength": 1},
-        "action": {"type": "string", "minLength": 1},
-        "store_revision": {"$ref": "#/$defs/sha256"},
-        "eligibility": {"$ref": "status.schema.json#/$defs/action_eligibility"},
-        "next_transition": {"$ref": "status.schema.json#/$defs/next_transition"}
-      }
+        "operation": {
+          "const": "review/finalize"
+        },
+        "lineage_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "state": {
+          "type": "string",
+          "minLength": 1
+        },
+        "action": {
+          "type": "string",
+          "minLength": 1
+        },
+        "store_revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "eligibility": {
+          "$ref": "status.schema.json#/$defs/action_eligibility"
+        },
+        "next_transition": {
+          "$ref": "status.schema.json#/$defs/next_transition"
+        },
+        "validation_request": {
+          "$ref": "targeted-validation-request.schema.json"
+        },
+        "escalation": {
+          "$comment": "Present only when the authority is escalated. Carries the accounting sentence with spent, remaining and total correction lines, so a caller learns the numbers without a second call.",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "required": [
+              "validation_request"
+            ]
+          },
+          "then": {
+            "properties": {
+              "state": {
+                "const": "correction_required"
+              }
+            }
+          }
+        }
+      ]
     },
     "validate": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["schema", "result", "allowed", "action", "reason", "context"],
+      "required": [
+        "schema",
+        "result",
+        "allowed",
+        "action",
+        "reason",
+        "context"
+      ],
       "properties": {
-        "schema": {"const": "gentle-ai.review-gate-result/v1"},
-        "result": {"enum": ["allow", "scope-changed", "invalidated", "escalated"]},
-        "allowed": {"type": "boolean"},
-        "action": {"type": "string", "minLength": 1},
-        "reason": {"type": "string", "minLength": 1},
-        "context": {"type": "object"}
+        "schema": {
+          "const": "gentle-ai.review-gate-result/v1"
+        },
+        "result": {
+          "enum": [
+            "allow",
+            "scope-changed",
+            "invalidated",
+            "escalated"
+          ]
+        },
+        "allowed": {
+          "type": "boolean"
+        },
+        "action": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        },
+        "context": {
+          "type": "object"
+        },
+        "delivery": {
+          "const": "disabled/unmanaged"
+        }
       }
     },
     "bind_sdd": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["schema", "revision", "change", "lineage", "authority_revision", "receipt_hash", "gate_context"],
+      "required": [
+        "schema",
+        "revision",
+        "change",
+        "lineage",
+        "authority_revision",
+        "receipt_hash",
+        "gate_context"
+      ],
+      "properties": {
+        "schema": {
+          "const": "gentle-ai.sdd-review-binding/v1"
+        },
+        "revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "change": {
+          "type": "string",
+          "minLength": 1
+        },
+        "lineage": {
+          "type": "string",
+          "minLength": 1
+        },
+        "authority_revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "receipt_hash": {
+          "$ref": "#/$defs/sha256"
+        },
+        "gate_context": {
+          "type": "object"
+        }
+      }
+    },
+    "retry_final_verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "operation",
+        "predecessor_lineage_id",
+        "predecessor_revision",
+        "lineage_id",
+        "state",
+        "store_revision",
+        "target_identity",
+        "incident_digest",
+        "recovery_disposition"
+      ],
       "properties": {
-        "schema": {"const": "gentle-ai.sdd-review-binding/v1"},
-        "revision": {"$ref": "#/$defs/sha256"},
-        "change": {"type": "string", "minLength": 1},
-        "lineage": {"type": "string", "minLength": 1},
-        "authority_revision": {"$ref": "#/$defs/sha256"},
-        "receipt_hash": {"$ref": "#/$defs/sha256"},
-        "gate_context": {"type": "object"}
+        "operation": {
+          "const": "review.retry_final_verification"
+        },
+        "predecessor_lineage_id": {
+          "type": "string",
+          "maxLength": 128,
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "predecessor_revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "lineage_id": {
+          "type": "string",
+          "maxLength": 128,
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "state": {
+          "const": "validating"
+        },
+        "store_revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "target_identity": {
+          "$ref": "#/$defs/sha256"
+        },
+        "incident_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "recovery_disposition": {
+          "const": "final_verification_retry"
+        }
       }
     }
   }

package/contracts/review-integration/v1/schemas/repair.schema.json

@@ -0,0 +1,251 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/repair.schema.json",
+  "title": "Gentle AI classified authority repair operation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "contract",
+    "operation",
+    "mode",
+    "assessment",
+    "required_inputs"
+  ],
+  "properties": {
+    "schema": {
+      "const": "gentle-ai.review-integration.repair/v1"
+    },
+    "contract": {
+      "const": "gentle-ai.review-integration/v1"
+    },
+    "operation": {
+      "const": "review.repair"
+    },
+    "mode": {
+      "enum": [
+        "preflight",
+        "execute"
+      ]
+    },
+    "assessment": {
+      "$ref": "authority-repair-assessment.schema.json"
+    },
+    "provider_inputs": {
+      "$ref": "#/$defs/provider_inputs"
+    },
+    "required_inputs": {
+      "type": "array",
+      "maxItems": 3,
+      "uniqueItems": true,
+      "items": {
+        "enum": [
+          "actor",
+          "reason",
+          "maintainer_authorization"
+        ]
+      }
+    },
+    "execution": {
+      "$ref": "#/$defs/execution"
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "mode": {
+            "const": "execute"
+          }
+        },
+        "required": [
+          "mode"
+        ]
+      },
+      "then": {
+        "required": [
+          "execution"
+        ],
+        "properties": {
+          "required_inputs": {
+            "maxItems": 0
+          }
+        },
+        "not": {
+          "required": [
+            "provider_inputs"
+          ]
+        }
+      },
+      "else": {
+        "not": {
+          "required": [
+            "execution"
+          ]
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "mode": {
+            "const": "preflight"
+          },
+          "assessment": {
+            "properties": {
+              "status": {
+                "const": "eligible"
+              }
+            },
+            "required": [
+              "status"
+            ]
+          }
+        },
+        "required": [
+          "mode",
+          "assessment"
+        ]
+      },
+      "then": {
+        "required": [
+          "provider_inputs"
+        ],
+        "properties": {
+          "required_inputs": {
+            "minItems": 3,
+            "maxItems": 3,
+            "prefixItems": [
+              {
+                "const": "actor"
+              },
+              {
+                "const": "reason"
+              },
+              {
+                "const": "maintainer_authorization"
+              }
+            ],
+            "items": false
+          }
+        }
+      },
+      "else": {
+        "if": {
+          "properties": {
+            "mode": {
+              "const": "preflight"
+            }
+          },
+          "required": [
+            "mode"
+          ]
+        },
+        "then": {
+          "properties": {
+            "required_inputs": {
+              "maxItems": 0
+            }
+          },
+          "not": {
+            "required": [
+              "provider_inputs"
+            ]
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "provider_inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "class",
+        "lineage_id",
+        "expected_revision",
+        "cause",
+        "disposition",
+        "repository_binding",
+        "authorization_schema"
+      ],
+      "properties": {
+        "class": {
+          "const": "legacy_v1_historical_alias"
+        },
+        "lineage_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "expected_revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "cause": {
+          "const": "unsupported_historical_v1_operation_alias"
+        },
+        "disposition": {
+          "const": "quarantine-approved-historical-alias"
+        },
+        "repository_binding": {
+          "$ref": "#/$defs/sha256"
+        },
+        "authorization_schema": {
+          "const": "gentle-ai.review-repair-authorization/v1"
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "class",
+        "lineage_id",
+        "revision",
+        "chain_identity",
+        "cause",
+        "disposition",
+        "assessment_digest",
+        "request_digest",
+        "record_identity"
+      ],
+      "properties": {
+        "status": {
+          "const": "committed"
+        },
+        "class": {
+          "const": "legacy_v1_historical_alias"
+        },
+        "lineage_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "revision": {
+          "$ref": "#/$defs/sha256"
+        },
+        "chain_identity": {
+          "$ref": "#/$defs/sha256"
+        },
+        "cause": {
+          "const": "unsupported_historical_v1_operation_alias"
+        },
+        "disposition": {
+          "const": "quarantine-approved-historical-alias"
+        },
+        "assessment_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "request_digest": {
+          "$ref": "#/$defs/sha256"
+        },
+        "record_identity": {
+          "$ref": "#/$defs/sha256"
+        }
+      }
+    }
+  }
+}