gentle-pi 1.2.0 → 2.0.0

package/contracts/review-integration/v1/schemas/status-v2.schema.json

@@ -0,0 +1,313 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/status-v2.schema.json",
+  "title": "Gentle AI Review Integration Target Status v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "contract",
+    "operation",
+    "applicability",
+    "receipt",
+    "action",
+    "replayability",
+    "target_identity",
+    "projection",
+    "repair",
+    "candidates"
+  ],
+  "properties": {
+    "schema": { "const": "gentle-ai.review-integration.status/v2" },
+    "contract": { "const": "gentle-ai.review-integration/v1" },
+    "operation": { "const": "review.status" },
+    "applicability": { "enum": ["current_target", "unrelated", "ambiguous", "corrupted"] },
+    "authority": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["version", "lineage_id", "state", "generation", "revision"],
+      "properties": {
+        "version": { "enum": ["compact-v2", "legacy-v1"] },
+        "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "state": { "type": "string", "minLength": 1 },
+        "generation": { "type": "integer", "minimum": 1 },
+        "revision": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "receipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status"],
+      "properties": {
+        "status": { "enum": ["expected_missing", "present", "publication_pending", "not_applicable"] },
+        "identity": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "action": { "enum": ["start", "finalize", "validate", "recover", "retry_final_verification", "maintainer_action", "select_lineage", "repair_authority", "reconcile_finalize", "stop"] },
+    "action_disposition": { "enum": ["scope_changed", "invalidated", "escalated", "final_verification_retry"] },
+    "replayability": { "enum": ["not_replayable", "exact_replay_safe", "status_required", "manual_action_required"] },
+    "frozen": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tier", "original_changed_lines", "correction_budget"],
+      "properties": {
+        "tier": { "enum": ["low", "medium", "high"] },
+        "original_changed_lines": { "type": "integer", "minimum": 0 },
+        "correction_budget": { "type": "integer", "minimum": 0, "maximum": 200 }
+      }
+    },
+    "target_identity": { "$ref": "#/$defs/sha256" },
+    "authority_target_identity": { "$ref": "#/$defs/sha256" },
+    "projection": { "$ref": "projection.schema.json" },
+    "repair": { "$ref": "authority-repair-assessment.schema.json" },
+    "candidates": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["required"],
+      "properties": { "required": { "const": true } }
+    },
+    "eligibility": { "$ref": "#/$defs/action_eligibility" },
+    "next_transition": { "$ref": "#/$defs/next_transition" },
+    "validation_request": { "$ref": "targeted-validation-request.schema.json" },
+    "final_verification_retry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["incident_schema", "incident_class", "validating_revision", "target_identity", "failed_evidence_hash", "finalize_request_digest"],
+      "properties": {
+        "incident_schema": { "const": "gentle-ai.review-final-verification-incident/v1" },
+        "incident_class": { "const": "procedural_tooling_failure" },
+        "validating_revision": { "$ref": "#/$defs/sha256" },
+        "target_identity": { "$ref": "#/$defs/sha256" },
+        "failed_evidence_hash": { "$ref": "#/$defs/sha256" },
+        "failed_evidence_record_digest": { "$ref": "#/$defs/sha256" },
+        "finalize_request_digest": { "$ref": "#/$defs/sha256" }
+      }
+    }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "next_transition": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "reason_code"],
+      "properties": {
+        "kind": { "enum": ["execute", "collect", "stop"] },
+        "reason_code": { "type": "string", "pattern": "^[a-z0-9_]+$" },
+        "execute": { "$ref": "#/$defs/transition_execution" },
+        "collect": { "$ref": "#/$defs/transition_collection" }
+      },
+      "allOf": [
+        { "if": { "properties": { "kind": { "const": "execute" } }, "required": ["kind"] }, "then": { "required": ["execute"], "not": { "required": ["collect"] } } },
+        { "if": { "properties": { "kind": { "const": "collect" } }, "required": ["kind"] }, "then": { "required": ["collect"], "not": { "required": ["execute"] } } },
+        { "if": { "properties": { "kind": { "const": "stop" } }, "required": ["kind"] }, "then": { "not": { "anyOf": [{ "required": ["execute"] }, { "required": ["collect"] }] } } }
+      ]
+    },
+    "transition_argument": {
+      "$comment": "One argument of a transition. \"token\", when present, is the exact argv token rendering this argument for a command this product runs, e.g. \"--lineage=review-abc\". It is required on an execute argument (see executable_transition_argument) and present on the arguments of a collect input whose capture_operation names an operation this product performs, because those arguments are literally that command's flags. It is absent on preconditions, on selector_arguments, and on the arguments of an \"external.*\" capture operation, which are assertions, a normalized echo, and values to hand elsewhere rather than argv.",
+      "type": "object", "additionalProperties": false, "required": ["name", "value"],
+      "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_-]+$" }, "value": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }
+    },
+    "executable_transition_argument": {
+      "$comment": "One argv entry of an execute transition. Unlike preconditions and selector_arguments -- which are assertions and a normalized echo the product never tokenizes -- an execute argument is always literally executed, so its exact runnable token is required rather than optional.",
+      "allOf": [{ "$ref": "#/$defs/transition_argument" }],
+      "type": "object", "required": ["name", "value", "token"]
+    },
+    "transition_binding": {
+      "type": "object", "additionalProperties": false, "required": ["target_identity"],
+      "properties": { "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "revision": { "$ref": "#/$defs/sha256" }, "target_identity": { "$ref": "#/$defs/sha256" }, "repository_context": { "type": "string", "pattern": "^rctx1_[0-9a-f]{64}$" } }
+    },
+    "transition_execution": {
+      "type": "object", "additionalProperties": false, "required": ["operation", "arguments", "preconditions", "binding"],
+      "properties": {
+        "operation": { "enum": ["review.start", "review.finalize", "review.recover", "review.repair", "review.validate"] },
+        "command": { "$comment": "The complete, literally runnable command line for this transition, e.g. \"gentle-ai review start --contract=... --target=...\". Operation alone is a dotted logical name; command is what a caller can paste. Argument words are the execute arguments' own tokens, in order, POSIX-shell-quoted only when a value would otherwise be word-split.", "type": "string", "minLength": 1, "pattern": "^gentle-ai review [a-z][a-z-]*" },
+        "arguments": { "type": "array", "items": { "$ref": "#/$defs/executable_transition_argument" } },
+        "selector_arguments": { "type": "array", "items": { "$ref": "#/$defs/transition_argument" } },
+        "preconditions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_argument" } },
+        "binding": { "$ref": "#/$defs/transition_binding" },
+        "artifacts": { "type": "array", "items": { "$ref": "#/$defs/transition_artifact" } }
+      }
+    },
+    "transition_artifact": {
+      "type": "object", "additionalProperties": false, "required": ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order", "subject_hash", "admission_decision"],
+      "properties": {
+        "schema": { "const": "gentle-ai.review-result-artifact/v2" }, "capability": { "const": "review.native_result_artifact" }, "sha256": { "$ref": "#/$defs/sha256" },
+        "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "target_identity": { "$ref": "#/$defs/sha256" }, "lens": { "type": "string", "minLength": 1 }, "selected_order": { "type": "integer", "minimum": 0 },
+        "subject_hash": { "$ref": "#/$defs/sha256" }, "admission_decision": { "const": "completed" }
+      }
+    },
+    "transition_collection": {
+      "type": "object", "additionalProperties": false, "required": ["inputs"],
+      "properties": { "inputs": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_input" } } }
+    },
+    "transition_input": {
+      "type": "object", "additionalProperties": false, "required": ["name", "schema", "capture_operation", "arguments"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9_]+$" }, "schema": { "type": "string", "minLength": 1 }, "capture_operation": { "type": "string", "minLength": 1 },
+        "arguments": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_argument" } },
+        "artifact_subject": { "$ref": "artifact-subject.schema.json" },
+        "candidate_diff": { "$ref": "start-v2.schema.json#/$defs/frozen_candidate_diff" },
+        "changed_path_manifest": { "type": "array", "uniqueItems": true, "items": { "$ref": "start-v2.schema.json#/$defs/changed_path" } },
+        "validation_request": { "$ref": "targeted-validation-request.schema.json" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "capture_operation": { "const": "external.run_targeted_validation" } }, "required": ["capture_operation"] },
+          "then": { "required": ["validation_request"], "properties": { "schema": { "const": "gentle-ai.review-targeted-validation-request/v1" } } },
+          "else": { "not": { "required": ["validation_request"] } }
+        },
+        {
+          "if": { "properties": { "capture_operation": { "const": "review.capture-result" } }, "required": ["capture_operation"] },
+          "then": { "required": ["artifact_subject", "candidate_diff", "changed_path_manifest"], "properties": { "schema": { "const": "https://gentle-ai.dev/schema/review/reviewer/v1" } } },
+          "else": {
+            "allOf": [
+              { "not": { "required": ["artifact_subject"] } },
+              { "not": { "required": ["candidate_diff"] } },
+              { "not": { "required": ["changed_path_manifest"] } }
+            ]
+          }
+        }
+      ]
+    },
+    "action_eligibility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allowed_actions", "forbidden_actions"],
+      "properties": {
+        "allowed_actions": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["action", "reason_code", "required_inputs"],
+            "properties": {
+              "action": { "enum": ["stop", "review.start", "review.finalize", "review.validate", "review.recover", "review.repair", "review.retry_final_verification"] },
+              "reason_code": { "type": "string", "pattern": "^[a-z0-9_]+$" },
+              "required_inputs": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9_]+$" } },
+              "disposition": { "enum": ["scope_changed", "invalidated", "escalated", "final_verification_retry"] },
+              "binding": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["lineage_id", "revision", "target_identity"],
+                "properties": {
+                  "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+                  "revision": { "$ref": "#/$defs/sha256" },
+                  "target_identity": { "$ref": "#/$defs/sha256" }
+                }
+              }
+            },
+            "allOf": [
+              {
+                "if": { "properties": { "action": { "enum": ["review.recover", "review.retry_final_verification"] } }, "required": ["action"] },
+                "then": { "required": ["disposition", "binding"] },
+                "else": { "not": { "anyOf": [{ "required": ["disposition"] }, { "required": ["binding"] }] } }
+              }
+            ]
+          }
+        },
+        "forbidden_actions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["action", "reason_code"],
+            "properties": {
+              "action": { "enum": ["review.abandon", "review.finalize", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.reconcile-authority-batch", "review.recover", "review.repair", "review.retry_final_verification", "review.start", "review.validate"] },
+              "reason_code": { "type": "string", "pattern": "^[a-z0-9_]+$" }
+            }
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "action": { "const": "reconcile_finalize" } } },
+      "then": {
+        "required": ["reconciliation"],
+        "properties": {
+          "applicability": { "const": "current_target" },
+          "replayability": { "const": "status_required" }
+        }
+      },
+      "else": { "not": { "required": ["reconciliation"] } }
+    },
+    {
+      "if": { "properties": { "action": { "enum": ["recover", "retry_final_verification"] } }, "required": ["action"] },
+      "then": { "required": ["action_disposition"] },
+      "else": { "not": { "required": ["action_disposition"] } }
+    },
+    {
+      "if": { "properties": { "applicability": { "const": "current_target" } } },
+      "then": { "required": ["authority"] },
+      "else": { "not": { "anyOf": [{ "required": ["authority"] }, { "required": ["frozen"] }, { "required": ["authority_target_identity"] }] } }
+    },
+    {
+      "if": {
+        "required": ["authority"],
+        "properties": {
+          "applicability": { "const": "current_target" },
+          "authority": {
+            "required": ["version"],
+            "properties": { "version": { "const": "compact-v2" } }
+          }
+        }
+      },
+      "then": { "required": ["frozen"] }
+    },
+    {
+      "if": {
+        "required": ["authority"],
+        "properties": {
+          "applicability": { "const": "current_target" },
+          "authority": {
+            "required": ["version"],
+            "properties": { "version": { "const": "legacy-v1" } }
+          }
+        }
+      },
+      "then": {
+        "not": { "anyOf": [{ "required": ["frozen"] }, { "required": ["authority_target_identity"] }] },
+        "properties": {
+          "receipt": {
+            "properties": { "status": { "enum": ["expected_missing", "present"] } }
+          }
+        }
+      }
+    },
+    {
+      "if": { "required": ["validation_request"] },
+      "then": {
+        "properties": {
+          "applicability": { "const": "current_target" },
+          "authority": { "properties": { "state": { "const": "correction_required" } }, "required": ["state"] }
+        }
+      }
+    },
+    {
+      "if": { "properties": { "action": { "const": "retry_final_verification" } }, "required": ["action"] },
+      "then": {
+        "required": ["final_verification_retry"],
+        "properties": {
+          "applicability": { "const": "current_target" },
+          "authority": {
+            "required": ["version", "state"],
+            "properties": {
+              "version": { "const": "compact-v2" },
+              "state": { "const": "escalated" }
+            }
+          },
+          "action_disposition": { "const": "final_verification_retry" }
+        }
+      },
+      "else": { "not": { "required": ["final_verification_retry"] } }
+    }
+  ]
+}

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

@@ -69,7 +69,8 @@
       "properties": { "required": { "const": true } }
     },
     "eligibility": { "$ref": "#/$defs/action_eligibility" },
-    "next_transition": { "$ref": "#/$defs/next_transition" }
+    "next_transition": { "$ref": "#/$defs/next_transition" },
+    "validation_request": { "$ref": "targeted-validation-request.schema.json" }
   },
   "$defs": {
     "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
@@ -90,28 +91,37 @@
       ]
     },
     "transition_argument": {
+      "$comment": "One argument of a transition. \"token\", when present, is the exact argv token rendering this argument for a command this product runs, e.g. \"--lineage=review-abc\". It is required on an execute argument (see executable_transition_argument) and present on the arguments of a collect input whose capture_operation names an operation this product performs, because those arguments are literally that command's flags. It is absent on preconditions, on selector_arguments, and on the arguments of an \"external.*\" capture operation, which are assertions, a normalized echo, and values to hand elsewhere rather than argv.",
       "type": "object", "additionalProperties": false, "required": ["name", "value"],
-      "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_-]+$" }, "value": { "type": "string", "minLength": 1 } }
+      "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_-]+$" }, "value": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }
+    },
+    "executable_transition_argument": {
+      "$comment": "One argv entry of an execute transition. Unlike preconditions and selector_arguments -- which are assertions and a normalized echo the product never tokenizes -- an execute argument is always literally executed, so its exact runnable token is required rather than optional.",
+      "allOf": [{ "$ref": "#/$defs/transition_argument" }],
+      "type": "object", "required": ["name", "value", "token"]
     },
     "transition_binding": {
       "type": "object", "additionalProperties": false, "required": ["target_identity"],
-      "properties": { "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "revision": { "$ref": "#/$defs/sha256" }, "target_identity": { "$ref": "#/$defs/sha256" } }
+      "properties": { "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "revision": { "$ref": "#/$defs/sha256" }, "target_identity": { "$ref": "#/$defs/sha256" }, "repository_context": { "type": "string", "pattern": "^rctx1_[0-9a-f]{64}$" } }
     },
     "transition_execution": {
       "type": "object", "additionalProperties": false, "required": ["operation", "arguments", "preconditions", "binding"],
       "properties": {
         "operation": { "enum": ["review.start", "review.finalize", "review.recover", "review.validate"] },
-        "arguments": { "type": "array", "items": { "$ref": "#/$defs/transition_argument" } },
+        "command": { "$comment": "The complete, literally runnable command line for this transition, e.g. \"gentle-ai review start --contract=... --target=...\". Operation alone is a dotted logical name; command is what a caller can paste. Argument words are the execute arguments' own tokens, in order, POSIX-shell-quoted only when a value would otherwise be word-split.", "type": "string", "minLength": 1, "pattern": "^gentle-ai review [a-z][a-z-]*" },
+        "arguments": { "type": "array", "items": { "$ref": "#/$defs/executable_transition_argument" } },
+        "selector_arguments": { "type": "array", "items": { "$ref": "#/$defs/transition_argument" } },
         "preconditions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_argument" } },
         "binding": { "$ref": "#/$defs/transition_binding" },
         "artifacts": { "type": "array", "items": { "$ref": "#/$defs/transition_artifact" } }
       }
     },
     "transition_artifact": {
-      "type": "object", "additionalProperties": false, "required": ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order"],
+      "type": "object", "additionalProperties": false, "required": ["schema", "capability", "sha256", "lineage_id", "target_identity", "lens", "selected_order", "subject_hash", "admission_decision"],
       "properties": {
-        "schema": { "const": "gentle-ai.review-result-artifact/v1" }, "capability": { "const": "review.native_result_artifact" }, "sha256": { "$ref": "#/$defs/sha256" },
-        "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "target_identity": { "$ref": "#/$defs/sha256" }, "lens": { "type": "string", "minLength": 1 }, "selected_order": { "type": "integer", "minimum": 0 }
+        "schema": { "const": "gentle-ai.review-result-artifact/v2" }, "capability": { "const": "review.native_result_artifact" }, "sha256": { "$ref": "#/$defs/sha256" },
+        "lineage_id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "target_identity": { "$ref": "#/$defs/sha256" }, "lens": { "type": "string", "minLength": 1 }, "selected_order": { "type": "integer", "minimum": 0 },
+        "subject_hash": { "$ref": "#/$defs/sha256" }, "admission_decision": { "const": "completed" }
       }
     },
     "transition_collection": {
@@ -122,8 +132,16 @@
       "type": "object", "additionalProperties": false, "required": ["name", "schema", "capture_operation", "arguments"],
       "properties": {
         "name": { "type": "string", "pattern": "^[a-z0-9_]+$" }, "schema": { "type": "string", "minLength": 1 }, "capture_operation": { "type": "string", "minLength": 1 },
-        "arguments": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_argument" } }
-      }
+        "arguments": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/transition_argument" } },
+        "validation_request": { "$ref": "targeted-validation-request.schema.json" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "capture_operation": { "const": "external.run_targeted_validation" } }, "required": ["capture_operation"] },
+          "then": { "required": ["validation_request"], "properties": { "schema": { "const": "gentle-ai.review-targeted-validation-request/v1" } } },
+          "else": { "not": { "required": ["validation_request"] } }
+        }
+      ]
     },
     "action_eligibility": {
       "type": "object",
@@ -170,7 +188,7 @@
             "additionalProperties": false,
             "required": ["action", "reason_code"],
             "properties": {
-              "action": { "enum": ["review.abandon", "review.finalize", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.recover", "review.start", "review.validate"] },
+              "action": { "enum": ["review.abandon", "review.finalize", "review.invalidate", "review.quarantine-legacy", "review.reclaim", "review.reconcile-authority", "review.reconcile-authority-batch", "review.recover", "review.start", "review.validate"] },
               "reason_code": { "type": "string", "pattern": "^[a-z0-9_]+$" }
             }
           }
@@ -232,6 +250,15 @@
           }
         }
       }
+    },
+    {
+      "if": { "required": ["validation_request"] },
+      "then": {
+        "properties": {
+          "applicability": { "const": "current_target" },
+          "authority": { "properties": { "state": { "const": "correction_required" } }, "required": ["state"] }
+        }
+      }
     }
   ]
 }

package/contracts/review-integration/v1/schemas/targeted-validation-request.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/targeted-validation-request.schema.json",
+  "title": "Gentle AI provider-owned targeted validation request",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "request_hash",
+    "lineage_id",
+    "expected_revision",
+    "target_identity",
+    "fix_finding_ids",
+    "projection",
+    "correction_candidate_tree",
+    "correction_target_identity",
+    "correction_paths",
+    "correction_paths_digest"
+  ],
+  "properties": {
+    "schema": {"const": "gentle-ai.review-targeted-validation-request/v1"},
+    "request_hash": {"$ref": "#/$defs/sha256"},
+    "lineage_id": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
+    "expected_revision": {"$ref": "#/$defs/sha256"},
+    "target_identity": {"$ref": "#/$defs/sha256"},
+    "fix_finding_ids": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "minLength": 1}
+    },
+    "projection": {"enum": ["workspace", "staged"]},
+    "correction_candidate_tree": {"type": "string", "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$"},
+    "correction_target_identity": {"$ref": "#/$defs/sha256"},
+    "correction_paths": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"type": "string", "minLength": 1}
+    },
+    "correction_paths_digest": {"$ref": "#/$defs/sha256"}
+  },
+  "$defs": {
+    "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
+  }
+}

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

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://gentle-ai.dev/contracts/review-integration/v1/schemas/verification-evidence.schema.json",
+  "title": "Gentle AI outcome-bearing verification evidence record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "version",
+    "lineage_id",
+    "authority_revision",
+    "target_identity",
+    "candidate_tree",
+    "paths_digest",
+    "paths",
+    "ledger_ids",
+    "raw_payload_sha256",
+    "raw_payload_bytes",
+    "outcome",
+    "record_digest"
+  ],
+  "properties": {
+    "schema": { "const": "gentle-ai.review-verification-evidence/v2" },
+    "version": { "const": 2 },
+    "lineage_id": {
+      "type": "string",
+      "maxLength": 128,
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "authority_revision": { "$ref": "#/$defs/sha256" },
+    "target_identity": { "$ref": "#/$defs/sha256" },
+    "candidate_tree": {
+      "type": "string",
+      "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+    },
+    "paths_digest": { "$ref": "#/$defs/sha256" },
+    "paths": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "ledger_ids": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "raw_payload_sha256": { "$ref": "#/$defs/sha256" },
+    "raw_payload_bytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 4194304
+    },
+    "outcome": {
+      "enum": ["passed", "verification_failed", "procedural_tooling_failed"]
+    },
+    "record_digest": { "$ref": "#/$defs/sha256" }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    }
+  }
+}