approval-md 0.4.5 → 0.4.7

package/schema/event.schema.json

@@ -136,7 +136,7 @@
           "minLength": 1,
           "maxLength": 64,
           "pattern": "^[\\u0020-\\u007e]+$",
-          "description": "SPEC.md §10.1 (amended, APRV-227): the version of the harness binary that issued this record, taken from the hook event where the harness supplies one and otherwise from `<binary> --version`, normalized to its first line. SELF-REPORTED, and informational only: nothing in the runtime reads it back as an input to a verdict, a floor, a budget, a streak or a sampling draw, so it satisfies SPEC.md §11.1 invariant 4 by having no path along which it could reduce scrutiny — its single reader is a doctor row that can only ADD a red line. Its SHAPE is constrained here because the value is the output of a third-party process being written to an append-only log: one line, printable ASCII, capped at 64 characters, so a banner or a stack trace (and whatever a stack trace quotes) cannot arrive through it. §11.1 invariant 3 has no exception for provenance. OPTIONAL and additive."
+          "description": "SPEC.md §10.1 (amended, APRV-227): the version of the harness binary that issued this record, taken from the hook event where the harness supplies one and otherwise from `<binary> --version`, normalized to its first line. SELF-REPORTED, and informational only: nothing in the runtime reads it back as an input to a verdict, a floor, a budget, a streak or a sampling draw, so it satisfies SPEC.md §11.1 invariant 4 by having no path along which it could reduce scrutiny — its single reader is a doctor row that can only ADD a red line. Its SHAPE is constrained here because the value is the output of a third-party process being written to an append-only log: one line, printable ASCII, capped at 64 characters, so a banner or a stack trace (and whatever a stack trace quotes) cannot arrive through it. §11.1 invariant 3 has no exception for provenance. APRV-419 chose option (c) in its no-schema form: a writer records the first line's printable-ASCII PREFIX, trimmed, cutting everything from the first character outside U+0020..U+007E, where it used to refuse the whole line. That is why a Hermes record carries `Hermes Agent v0.21.3 (2026.9.14)` from the line `Hermes Agent v0.21.3 (2026.9.14) \u00b7 upstream 913d4098`. Every value the prefix rule produces already satisfied this pattern and cap, so neither moved and no record changes validity. OPTIONAL and additive."
         },
         "est_cost_usd": {
           "$ref": "#/$defs/usd_amount",
@@ -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"
+}

package/schema/fixtures/policy/invalid/exec-code-custody-boolean.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "exec": {
+    "code": {
+      "custody": true
+    }
+  }
+}

package/schema/fixtures/policy/invalid/exec-code-execute-code-value.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "exec": {
+    "code": {
+      "execute_code": "yes"
+    }
+  }
+}

package/schema/fixtures/policy/invalid/exec-code-unknown-key.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "exec": {
+    "code": {
+      "custody": "attested",
+      "inline": "on"
+    }
+  }
+}

package/schema/fixtures/policy/valid/exec-code-both.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "exec": {
+    "code": {
+      "custody": "attested",
+      "execute_code": "hooked"
+    }
+  },
+  "classes": {
+    "exec.code": {
+      "autonomy": "autonomous"
+    }
+  }
+}

package/schema/fixtures/policy/valid/exec-code-custody.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.1",
+  "defaults": {
+    "autonomy": "manual"
+  },
+  "exec": {
+    "code": {
+      "custody": "attested"
+    }
+  }
+}

package/schema/policy.schema.json

@@ -197,6 +197,29 @@
         }
       ]
     },
+    "exec": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2 and §7 (APRV-510, proposed; 0.4.5 candidate): what an operator has attested about opaque agent code. Absent, every policy behaves exactly as before the key existed: `python3 -c`, `node -e` and kin are refused `hook-opaque`, an interpreter running a file that is not a skill script is refused `hook-unclassified`, and a Hermes `execute_code` call is refused `hook-hermes-execute-code-unbound`. A core that predates this key refuses it at the schema, and the whole policy then fails closed (every class `manual`), so a tenant receives this block only after its pinned core knows it.",
+      "properties": {
+        "code": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The `exec.code` class (APRV-510). Each key opens one thing and only the attested policy can set it; an absent key is the closed answer. With `custody: attested`, an inline program or a non-skill interpreter file run is classified `exec.code` and resolved by the policy like any class (an `exec.code` row, an `exec.*` family row, or `defaults.autonomy`), and a record of it binds the program's SHA-256 and length, never its text. The record says the program existed; it authorizes nothing the program then does through other tools, each of which is its own hook event.",
+          "properties": {
+            "custody": {
+              "enum": ["attested", "unattested"],
+              "description": "`attested`: the operator states that credential custody is in place for this agent (the code it runs cannot read credentials it should not hold), which is the precondition for opening the class at all, because opaque code run without it bypasses every gate that guards a credential. `unattested`, or the key absent: the class stays closed, and where the policy names `exec.code` anywhere the refusal is `hook-exec-code-custody-unattested`, naming this key."
+            },
+            "execute_code": {
+              "enum": ["hooked", "unhooked"],
+              "description": "Hermes `execute_code` only, and only beside `custody: attested`. `hooked`: the operator has observed that a tool call made from inside the `execute_code` kernel re-fires the hook (the lane L1 probe's answer), so the call is classified `exec.code` with the program's hash bound. `unhooked`, or the key absent: `execute_code` is refused `hook-hermes-execute-code-unbound` as before. Set it only on the probe's yes: if inner calls do not re-fire the hook, one `execute_code` call is an unbounded bypass of the whole adapter."
+            }
+          }
+        }
+      },
+      "examples": [{ "code": { "custody": "attested" } }, { "code": { "custody": "attested", "execute_code": "hooked" } }]
+    },
     "read_scope": {
       "type": "object",
       "additionalProperties": false,