approval-md 0.4.6 → 0.4.7

package/schema/event.schema.json

@@ -2750,6 +2750,218 @@
           }
         }
       }
+    },
+    {
+      "$comment": "SPEC.md §8 (amended, the study record): `payload.study` says why a study denied a request, and a study may only deny. So the field is admitted on `approval.rejected` alone and refused on every other event, `approval.granted`, `approval.revoked` and `approval.withdrawn` among them: a grant carrying it would read as a study approving something, which no study surface can do.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "study": true
+            },
+            "required": [
+              "study"
+            ]
+          }
+        },
+        "required": [
+          "payload"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "approval.rejected"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      }
+    },
+    {
+      "$comment": "SPEC.md §8 (amended, the study record): the shape of `payload.study` on `approval.rejected`, and the record fields each reason binds. Closed, with two reasons. `study_withdrawn` is a hosted operator denying a still-pending request: it names the operator (`operator`, 8 hex of the SHA-256 of the lower-cased staff email, never the email) and the withdraw's replay reference (`ref`), and the record is written under `human:study-team` on channel `study`, so a reader can always tell it from a resident's answer. `looks_wrong` is the resident's own deny with a flag: it names no operator and no reference, and it arrives on `telegram`, the one channel that draws the button. No enforcement path reads this field; a reader that ignores it reads an ordinary rejection.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "approval.rejected"
+          },
+          "payload": {
+            "type": "object",
+            "properties": {
+              "study": true
+            },
+            "required": [
+              "study"
+            ]
+          }
+        },
+        "required": [
+          "event",
+          "payload"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "study": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "reason"
+                ],
+                "properties": {
+                  "reason": {
+                    "type": "string",
+                    "enum": [
+                      "study_withdrawn",
+                      "looks_wrong"
+                    ],
+                    "description": "SPEC.md §8 (amended): why the study denied. `study_withdrawn`: a hosted operator withdrew the pending request before it could run. `looks_wrong`: the resident flagged the card as a suspected study card and skipped it."
+                  },
+                  "operator": {
+                    "type": "string",
+                    "pattern": "^[0-9a-f]{8}$",
+                    "description": "The first 8 hex of the SHA-256 of the withdrawing operator's lower-cased staff email. Derivable from the staff list and never the email itself. `study_withdrawn` only."
+                  },
+                  "ref": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9_-]{16,64}$",
+                    "description": "The withdraw's replay reference, minted once by the operator's tooling; the log is its idempotency authority. `study_withdrawn` only."
+                  }
+                },
+                "allOf": [
+                  {
+                    "if": {
+                      "type": "object",
+                      "properties": {
+                        "reason": {
+                          "const": "study_withdrawn"
+                        }
+                      },
+                      "required": [
+                        "reason"
+                      ]
+                    },
+                    "then": {
+                      "type": "object",
+                      "properties": {
+                        "operator": true,
+                        "ref": true
+                      },
+                      "required": [
+                        "operator",
+                        "ref"
+                      ]
+                    }
+                  },
+                  {
+                    "if": {
+                      "type": "object",
+                      "properties": {
+                        "reason": {
+                          "const": "looks_wrong"
+                        }
+                      },
+                      "required": [
+                        "reason"
+                      ]
+                    },
+                    "then": {
+                      "type": "object",
+                      "properties": {
+                        "operator": false,
+                        "ref": false
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "type": "object",
+              "properties": {
+                "payload": {
+                  "type": "object",
+                  "properties": {
+                    "study": {
+                      "type": "object",
+                      "properties": {
+                        "reason": {
+                          "const": "study_withdrawn"
+                        }
+                      },
+                      "required": [
+                        "reason"
+                      ]
+                    }
+                  }
+                }
+              }
+            },
+            "then": {
+              "type": "object",
+              "properties": {
+                "actor": {
+                  "const": "human:study-team"
+                },
+                "channel": {
+                  "const": "study"
+                }
+              },
+              "required": [
+                "actor",
+                "channel"
+              ]
+            }
+          },
+          {
+            "if": {
+              "type": "object",
+              "properties": {
+                "payload": {
+                  "type": "object",
+                  "properties": {
+                    "study": {
+                      "type": "object",
+                      "properties": {
+                        "reason": {
+                          "const": "looks_wrong"
+                        }
+                      },
+                      "required": [
+                        "reason"
+                      ]
+                    }
+                  }
+                }
+              }
+            },
+            "then": {
+              "type": "object",
+              "properties": {
+                "channel": {
+                  "const": "telegram"
+                }
+              },
+              "required": [
+                "channel"
+              ]
+            }
+          }
+        ]
+      }
     }
   ]
 }

package/schema/fixtures/event/invalid/approval-granted-study.json

@@ -0,0 +1,23 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.granted",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "telegram",
+  "payload": {
+    "note": "approved via telegram",
+    "sender": {
+      "channel": "telegram",
+      "id": "42"
+    },
+    "sender_source": "policy",
+    "study": {
+      "reason": "looks_wrong"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-looks-wrong-cli-channel.json

@@ -0,0 +1,23 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "cli",
+  "payload": {
+    "note": "rejected via telegram (callback cb-1)",
+    "sender": {
+      "channel": "telegram",
+      "id": "42"
+    },
+    "sender_source": "policy",
+    "study": {
+      "reason": "looks_wrong"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-looks-wrong-operator.json

@@ -0,0 +1,24 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "telegram",
+  "payload": {
+    "note": "rejected via telegram (callback cb-1)",
+    "sender": {
+      "channel": "telegram",
+      "id": "42"
+    },
+    "sender_source": "policy",
+    "study": {
+      "reason": "looks_wrong",
+      "operator": "3f9a01c2"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-extra-key.json

@@ -0,0 +1,24 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "telegram",
+  "payload": {
+    "note": "rejected via telegram (callback cb-1)",
+    "sender": {
+      "channel": "telegram",
+      "id": "42"
+    },
+    "sender_source": "policy",
+    "study": {
+      "reason": "looks_wrong",
+      "card": "study-card-7"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-unknown-reason.json

@@ -0,0 +1,23 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "telegram",
+  "payload": {
+    "note": "rejected via telegram (callback cb-1)",
+    "sender": {
+      "channel": "telegram",
+      "id": "42"
+    },
+    "sender_source": "policy",
+    "study": {
+      "reason": "suspicious"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-withdrawn-email-operator.json

@@ -0,0 +1,20 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:study-team",
+  "channel": "study",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "operator": "ops@example.org",
+      "ref": "wd_7Hq2LmX9pR4sT1vB"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-withdrawn-no-operator.json

@@ -0,0 +1,19 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:study-team",
+  "channel": "study",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "ref": "wd_7Hq2LmX9pR4sT1vB"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-withdrawn-no-ref.json

@@ -0,0 +1,19 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:study-team",
+  "channel": "study",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "operator": "3f9a01c2"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-withdrawn-wrong-actor.json

@@ -0,0 +1,20 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "study",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "operator": "3f9a01c2",
+      "ref": "wd_7Hq2LmX9pR4sT1vB"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-rejected-study-withdrawn-wrong-channel.json

@@ -0,0 +1,20 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:study-team",
+  "channel": "telegram",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "operator": "3f9a01c2",
+      "ref": "wd_7Hq2LmX9pR4sT1vB"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/invalid/approval-revoked-study.json

@@ -0,0 +1,20 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.revoked",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "cli",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "operator": "3f9a01c2",
+      "ref": "wd_7Hq2LmX9pR4sT1vB"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/valid/approval-rejected-looks-wrong.json

@@ -0,0 +1,23 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:carter",
+  "channel": "telegram",
+  "payload": {
+    "note": "rejected via telegram (callback cb-1)",
+    "sender": {
+      "channel": "telegram",
+      "id": "42"
+    },
+    "sender_source": "policy",
+    "study": {
+      "reason": "looks_wrong"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}

package/schema/fixtures/event/valid/approval-rejected-study-withdrawn.json

@@ -0,0 +1,20 @@
+{
+  "seq": 9,
+  "ts": "2026-10-20T09:16:02Z",
+  "event": "approval.rejected",
+  "task": "task-study",
+  "action_key": "task-study:send:2026-10-20",
+  "actor": "human:study-team",
+  "channel": "study",
+  "payload": {
+    "note": "withdrawn by the study team",
+    "study": {
+      "reason": "study_withdrawn",
+      "operator": "3f9a01c2",
+      "ref": "wd_7Hq2LmX9pR4sT1vB"
+    }
+  },
+  "alg": "sha256/jcs",
+  "prev": "bcd21fd125d9c85cc4b4eb1ff519448989c72c0fd70305cbb06b821d04926686",
+  "hash": "5b1e0c7d2a94f3e8b6c1d0a7f5e2c9b84d3a6f1e0c7b2d9a8e5f4c3b2a1d0e9f"
+}