approval-md 0.2.0 → 0.4.0

package/schema/event.schema.json

@@ -52,6 +52,8 @@
         "audit.reviewed",
         "audit.dark_session",
         "audit.decision_refused",
+        "audit.gesture_refused",
+        "audit.question_preempted",
         "reconciliation.required",
         "reconciliation.satisfied",
         "payload.pruned",
@@ -59,9 +61,10 @@
         "gate.closed",
         "gate.bypassed",
         "gate.organ.attested",
+        "gate.path.signed_off",
         "log.checkpoint"
       ],
-      "description": "SPEC.md §8 'Event types (v0.1)': the closed set of thirty-one event types. Closed by design — an unrecognized type fails closed at the write boundary rather than entering the log unvalidated. `payload.pruned` (APRV-38) is the first addition after the v0.1 draft set of sixteen, `approval.withdrawn` (APRV-106) the second, `execution.indeterminate` with `execution.reconciled` (APRV-120) the third and fourth, `reconciliation.required` / `reconciliation.satisfied` (APRV-127) the fifth and sixth, `policy.proposed` / `policy.declined` (APRV-109) the seventh and eighth, `audit.dark_session` (APRV-192) the ninth, `gate.opened` / `gate.closed` / `gate.bypassed` (APRV-214) the tenth, eleventh and twelfth, `log.checkpoint` (APRV-220) the thirteenth, `audit.decision_refused` (APRV-235) the fourteenth, and `gate.organ.attested` (APRV-272) the fifteenth: a reader of a v0.1 log may encounter any of them, and a verifier written against the draft enum must be updated to accept them all."
+      "description": "SPEC.md §8 'Event types (v0.1)': the closed set of thirty-four event types. Closed by design — an unrecognized type fails closed at the write boundary rather than entering the log unvalidated. `payload.pruned` (APRV-38) is the first addition after the v0.1 draft set of sixteen, `approval.withdrawn` (APRV-106) the second, `execution.indeterminate` with `execution.reconciled` (APRV-120) the third and fourth, `reconciliation.required` / `reconciliation.satisfied` (APRV-127) the fifth and sixth, `policy.proposed` / `policy.declined` (APRV-109) the seventh and eighth, `audit.dark_session` (APRV-192) the ninth, `gate.opened` / `gate.closed` / `gate.bypassed` (APRV-214) the tenth, eleventh and twelfth, `log.checkpoint` (APRV-220) the thirteenth, `audit.decision_refused` (APRV-235) the fourteenth, `gate.organ.attested` (APRV-272) the fifteenth, `gate.path.signed_off` (APRV-338) the sixteenth, `audit.gesture_refused` (APRV-355) the seventeenth, and `audit.question_preempted` (APRV-378) the eighteenth: a reader of a v0.1 log may encounter any of them, and a verifier written against the draft enum must be updated to accept them all."
     },
     "actor": {
       "type": "string",
@@ -89,6 +92,13 @@
         }
       ]
     },
+    "daemon": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "SPEC.md §8 (amended, APRV-383): WHICH daemon instance appended this record. Present exactly on the records a daemon wrote, so a tenant whose daemon is hosted by another party can open their own log and tell which host process acted on their behalf — before this field every daemon-written record carried the same generic `system:daemon` actor and nothing else. The value is either the id declared in the daemon's launch environment (`APPROVAL_DAEMON_ID`) or `daemon-` followed by the eight hex digits of the instance id `approval doctor` prints as its `keychain-scope` suffix, so it is stable across restarts on one machine and keystore without anything being stored.\n\nOPTIONAL and additive: every record written before the field existed still validates and still verifies, and the ABSENCE of the field is absence — it is never read as a claim that no daemon wrote the record, because until this task no daemon could say.\n\nSELF-REPORTED, and bounded by SPEC.md §11.1 invariant 4 in the only way a self-reported field may be: a policy MAY list the ids permitted to write (`daemons` in `policy.schema.json`), an id the list does not name is REFUSED at the write boundary (`daemon-not-allowed`), and an id the list DOES name gains nothing at all — no verdict, autonomy, budget, floor, sampling draw, token or TTL reads this field or that list. Its SHAPE is constrained here for the reason `payload.harness_version`'s is: the value comes from a launch environment and is being written into an append-only log, so a banner, a path, a newline or a shell fragment cannot arrive through it, and two ids differing only in case would be two ids nobody can tell apart on a phone."
+    },
     "task": {
       "type": "string",
       "minLength": 1,
@@ -113,9 +123,12 @@
           "enum": [
             "claude-code",
             "cursor",
-            "codex"
+            "codex",
+            "grok",
+            "muse",
+            "hermes"
           ],
-          "description": "SPEC.md §10.1 (amended, APRV-227): which harness hook wrote this record. A closed set, extended only by a task that adds the case, because it is the discriminator a reader scopes `harness_version` by: one log holds the records of every harness that ever wrote to it, and a version with no binary named beside it is a string nobody can compare against anything. OPTIONAL and additive — every record written before the field existed still validates and still verifies, and the two fields travel together or not at all."
+          "description": "SPEC.md §10.1 (amended, APRV-227): which harness hook wrote this record. A closed set, extended only by a task that adds the case, because it is the discriminator a reader scopes `harness_version` by: one log holds the records of every harness that ever wrote to it, and a version with no binary named beside it is a string nobody can compare against anything. OPTIONAL and additive — every record written before the field existed still validates and still verifies, and the two fields travel together or not at all. APRV-358 added `grok`, which APRV-243 shipped an adapter for and never added here: a Grok session's manual-class registration failed validation at the write boundary, so the request never reached a human. Closed does not mean hand-maintained any more. This list is pinned set-equal to `HARNESS_KINDS` in `src/core/harness-version.ts` by `tests/harness-enum.test.ts`, along with every other place a harness name is enumerated, so the next adapter cannot land with the enum left behind. APRV-398 added `hermes`, the Hermes Agent adapter, through that pinning rather than after it."
         },
         "harness_version": {
           "type": "string",
@@ -184,6 +197,34 @@
     }
   },
   "$defs": {
+    "senderHashed": {
+      "const": true,
+      "description": "SPEC.md §5.2/§10.3 (amended, APRV-370): the sibling `id` is the operator's KEYED digest of the account, `hmac-sha256:<64 lowercase hex>` — HMAC-SHA-256 of the transport's own account id under a secret named by `APPROVAL_SENDER_KEY` — rather than the account id itself. It appears exactly when the attested `approvers[id].senders` mapping for that channel is written in the keyed form, which is what a deployment that PUBLISHES its policy and its log uses so that neither discloses the account.\n\n`true` or ABSENT, never `false`, and that asymmetry is deliberate: absent is the raw form, which is the record every build since APRV-324 has written, and a `false` here would make all of those read afterwards as though they were missing something. The digest is not a credential either — it is published in the policy — and it is not an authenticator: nothing in the gate's safety rests on the key's secrecy, and a process that loses the key loses the ability to RESOLVE accounts, never the ability to refuse.",
+      "examples": [true]
+    },
+    "senderHashedImpliesDigest": {
+      "$comment": "APRV-370. `hashed` and `id` describe the same fact in two shapes, and two shapes of one fact can disagree. They cannot here: whenever the flag is present the id must be the digest form, so a record claiming to be hashed while carrying a bare account id does not validate, and a reader may branch on the boolean without parsing the string. The converse is deliberately NOT required — an id that merely looks like a digest is not asserted to be one — because the assertion is the flag's to make.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "hashed": {
+            "const": true
+          }
+        },
+        "required": [
+          "hashed"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^hmac-sha256:[0-9a-f]{64}$"
+          }
+        }
+      }
+    },
     "usd_amount_string": {
       "type": "string",
       "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{0,5}[1-9])?$",
@@ -719,6 +760,11 @@
                 "type": "integer",
                 "minimum": 1,
                 "description": "The `policy.proposed` record this attestation answers."
+              },
+              "payload_hash": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$",
+                "description": "SPEC.md §5.2/§10.4 (APRV-356): the binding for the ATTESTED policy text, stored beside the log, so the policy in force is recoverable and not only nameable. A digest alone cannot produce the file it names, and the privileged-gesture rule of §10.3 has to be decided against the policy in force rather than the one being proposed. Optional and additive: records written before this existed still validate and verify, and a reader treats absence as the pre-amendment state, where the in-force bytes are unrecoverable and the fail-closed fallback applies. A reader that recovers the text MUST re-hash it against `sha256` from the verified log, so the store is checked rather than trusted."
               }
             }
           }
@@ -795,6 +841,36 @@
         }
       }
     },
+    {
+      "$comment": "SPEC.md §8 (amended, APRV-447, pending sign-off): a harness `execution.started` carries `policy_sha256`, the SHA-256 of the attested policy the write boundary re-checked the action's class against when it recorded the start (on the hook route the verdict was drawn from the hook's own earlier read, so a re-attest landing between the two leaves the stamp naming the policy in force at the append). Before it, a policy-authorized start (autonomous, supervised, an unselected supervised-live draw) named no policy at all, and a reader had to reconstruct the rules in force from the latest `policy.updated` before the record's seq; a granted start could reach its policy through `grant_seq` and carries the stamp too, written by the same code. The runtime assigns the value at the write boundary from its own attestation check, exactly as it assigns `policy_sha256` on `approval.requested` and `ts` on every gate-typed event: no caller parameter carries it, and a caller-supplied value of the same name is ignored. No verdict, budget, draw or refusal reads it back, so §11.1 invariant 4 is untouched. It is covered by the record hash like every other payload field. OPTIONAL and additive: every record written before the field existed still validates and still verifies, an `execution.started` written by any other path records none, and only the SHAPE is constrained here, a 64-character lowercase hex digest. Whether the hash names an attestation the log actually carries is not expressible in a schema that sees one record. The field name is a stable contract: downstream followers of the log use it to join a start to the rules it ran under.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "execution.started"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "policy_sha256": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$",
+                "description": "SPEC.md §8 (amended, APRV-447): SHA-256 (lowercase hex) of the attested policy file's exact bytes the write boundary re-checked this start's class against, stamped by the runtime at the write boundary. Never a caller's parameter and never an input to a verdict.",
+                "examples": ["5f1c0de9a3b7e2d4c6f8091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e"]
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "$comment": "SPEC.md §10.3 (amended, APRV-38): a decision collected as part of a batch gesture carries the batch's channel delivery id as a first-class payload field. Optional — a unit decision has no batch — and constrained only when present, so the field can never arrive as an empty string or a number that audit would have to guess at.",
       "if": {
@@ -828,6 +904,140 @@
         }
       }
     },
+    {
+      "$comment": "SPEC.md §6.3/§10.3 (amended, APRV-324): who decided, as evidence rather than as configuration. `sender` is the account the channel's own transport attributed the gesture to — for Telegram the numeric `callback_query.from.id` — and the record's `actor` is the human the attested `approvers[id].senders` mapping binds that account to. Both optional and both additive: a decision made on a surface that authenticates no sender, or under a policy that maps none, carries neither key and is byte-identical to a decision written before they existed. That ABSENCE is meaningful and is why the fields are not defaulted: it says the attribution came from the identity the deciding process was launched with, which is the whole of what every build before APRV-324 could say. What may never appear here is anything the sender says about themselves: the mapping key is the transport's attribution, never a name, handle or id a message body claims (§11.1 invariant 4), and `from.username` is deliberately absent from the vocabulary because it is mutable and reusable and a log carrying it would grow a field that reads like identity and decays into a lie. `sender_source` names the kind of evidence, as a closed vocabulary, so a later source is distinguishable in a log rather than silently mixed in with policy-attested ones.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "enum": [
+              "approval.granted",
+              "approval.rejected",
+              "approval.revoked"
+            ]
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "sender": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "channel",
+                  "id"
+                ],
+                "description": "The authenticated sender the `actor` was resolved from. Present only where a transport authenticated one and the attested policy mapped it.",
+                "properties": {
+                  "channel": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The surface that observed the sender: `telegram`. Named separately from the record's own `channel` because a sender id is only meaningful inside the namespace that issued it."
+                  },
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The transport's own account id, as a string, OR the operator's keyed digest of it when `hashed` is true. Raw, it is not a credential — a Telegram user id is visible to everyone in a chat — and it is recorded so an operator investigating a decision has the number rather than a name they cannot check."
+                  },
+                  "hashed": {
+                    "$ref": "#/$defs/senderHashed"
+                  }
+                },
+                "allOf": [
+                  {
+                    "$ref": "#/$defs/senderHashedImpliesDigest"
+                  }
+                ],
+                "examples": [
+                  { "channel": "telegram", "id": "12345678" },
+                  {
+                    "channel": "telegram",
+                    "id": "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a",
+                    "hashed": true
+                  }
+                ]
+              },
+              "sender_source": {
+                "type": "string",
+                "enum": [
+                  "policy"
+                ],
+                "description": "How the sender became the actor. `policy` is the attested `approvers[id].senders` mapping of SPEC.md §5.2, and it is the only member today. A closed vocabulary on purpose: a future source of the same shape must be distinguishable from an operator's attestation rather than read back as one."
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "SPEC.md §10.3 (amended, APRV-324): the same two fields on the other human acts a channel collects. An attestation decides which rules are in force and a retrospective review is handed to agents as human-authored guidance, so both are recorded as a person's and both are worth attributing to an account rather than to whichever process was listening. Optional and additive on exactly the terms the decision events carry them: absent means the attribution came from the deciding process's configuration. `log.checkpoint` is deliberately NOT in this list — its payload is a signed structure, and an unsigned field sitting beside a signature invites a reader to treat it as covered by one; a checkpoint tap resolves its ACTOR from the sender exactly as these do, and the account it came from is not written next to the signature.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "enum": [
+              "policy.updated",
+              "policy.declined",
+              "audit.reviewed"
+            ]
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "sender": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "channel",
+                  "id"
+                ],
+                "description": "The authenticated sender the `actor` was resolved from, on the same terms as a decision's.",
+                "properties": {
+                  "channel": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "id": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "hashed": {
+                    "$ref": "#/$defs/senderHashed"
+                  }
+                },
+                "allOf": [
+                  {
+                    "$ref": "#/$defs/senderHashedImpliesDigest"
+                  }
+                ]
+              },
+              "sender_source": {
+                "type": "string",
+                "enum": [
+                  "policy"
+                ],
+                "description": "How the sender became the actor. `policy` is the attested `approvers[id].senders` mapping of SPEC.md §5.2 — and for an attestation specifically, the mapping of the policy IN FORCE, never the one being attested."
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "$comment": "SPEC.md §5.2/§8 (amended, APRV-118): a request and the grant that answers it each pin the SHA-256 of the attested policy the runtime evaluated them under, so a reader can see whether the approver decided by the rules the requester was routed by. The runtime assigns the value at the write boundary from its own attestation check, exactly as it assigns `ts` to a gate-typed event; a grant whose hash differs from its request's is refused `policy-drift` and never reaches this schema. Optional, and deliberately: the field is additive, so records written before it existed still validate and still verify, and only its SHAPE is constrained here — a 64-character lowercase hex digest, never an empty string or a truncated one that audit would have to guess at. Whether the hash names an attestation the log actually carries is not expressible in a schema that sees one record, and is the gate's check.",
       "if": {
@@ -954,6 +1164,25 @@
                 "type": "string",
                 "pattern": "^[a-f0-9]{64}$",
                 "description": "SPEC.md §9/§10.3 (APRV-119): SHA-256 (lowercase hex) over the UTF-8 text of the canonical rendering of this request's payload, as produced by the versioned deterministic renderer named inside that text."
+              },
+              "harness_cap_ms": {
+                "type": "integer",
+                "minimum": 60001,
+                "maximum": 86400000,
+                "description": "SPEC.md §6 (APRV-423): the ceiling, in milliseconds, that the harness running the requesting hook imposes on that hook's own process — Hermes caps a `pre_tool_call` entry at 300 s, Claude Code kills the hook at the `timeout` in its settings file. A BOUNDED INPUT and never a deadline of its own: the runtime judges the request against the SHORTER of this minus a fixed margin and the policy's `defaults.approval_ttl`, so a stated cap can only move the lapse EARLIER (§11.1 invariant 4). The minimum is HARNESS_CAP_MARGIN_MS + 1 (src/core/harness-wait.ts, 60 000 ms; tests/harness-cap-ttl.test.ts pins the two equal): a cap at or below the margin leaves a zero-length window, a question that lapses as it is asked, and the hook refuses such a configuration before it appends, so a record carrying one could only come from a caller that skipped the hook and is refused here. Above 24 h is a number no harness contract states."
+              }
+            },
+            "dependentSchemas": {
+              "harness_cap_ms": {
+                "$comment": "APRV-423. A record carrying a harness ceiling MUST also declare `execution: \"harness\"`. The ceiling shortens the window in which this request may be decided, and a request that mints an execution token would otherwise hold an authorization with a longer shelf life than the question that produced it. A schema sees one record, which is exactly enough to see both fields, so the pairing is refused at the write boundary rather than left to a caller's discipline.",
+                "properties": {
+                  "execution": {
+                    "const": "harness"
+                  }
+                },
+                "required": [
+                  "execution"
+                ]
               }
             }
           }
@@ -1245,9 +1474,10 @@
               "reason": {
                 "type": "string",
                 "enum": [
-                  "act-threw"
+                  "act-threw",
+                  "workspace-commit-unknown"
                 ],
-                "description": "Where the unknowing began. `act-threw`: the adapter's `act` was entered and raised, so the provider call may or may not have committed. Closed, and extended only by a task that adds the case."
+                "description": "Where the unknowing began. `act-threw`: the adapter's `act` was entered and raised, so the provider call may or may not have committed. `workspace-commit-unknown` (APRV-325.2): a multi-file workspace transaction was applied and the workspace then read back as neither the approved before-state nor the approved after-state, because POSIX offers no atomic multi-file rename and a crash, a permission error or a failed rollback can land between two of them; the transaction journal naming both states is retained for a person. Closed, and extended only by a task that adds the case."
               },
               "exit_code": {
                 "type": "null",
@@ -1390,9 +1620,10 @@
                 "type": "string",
                 "enum": [
                   "no-records",
-                  "no-evidence"
+                  "no-evidence",
+                  "no-evidence-merged"
                 ],
-                "description": "Which arm found it: `no-records` is git activity with no attributable hook record at all, `no-evidence` is a guarded path changed with no evidence a human decided it (the spelling APRV-151's CI guard already uses)."
+                "description": "Which arm found it: `no-records` is git activity with no attributable hook record at all, `no-evidence` is a guarded path changed with no evidence a human decided it (the spelling APRV-151's CI guard already uses), and `no-evidence-merged` (APRV-369) is that same finding where every failing commit reached the checkout through a merge rather than being authored on it — the same `dark` verdict, reported under its own code because the subject named it the checkout that SYNCED the change and the repair is in the branch the commit came from. A closed set, and `tests/dark-session.test.ts` pins it equal to the codes a `dark` verdict can carry, so a code the sweep can produce cannot be missing here: a record refused at the write boundary is an observation that never reaches a human."
               },
               "observation_key": {
                 "type": "string",
@@ -1464,7 +1695,6 @@
           "payload": {
             "type": "object",
             "required": [
-              "actor",
               "decision",
               "code"
             ],
@@ -1472,7 +1702,45 @@
               "actor": {
                 "type": "string",
                 "pattern": "^human:",
-                "description": "The person whose decision was refused, `human:<id>`. Distinct from the record's own `actor`, which is the runtime: this field is the SUBJECT of the observation, and the record's actor is its author. `^human:` because this event exists only for a human decision; a refusal handed to an agent is not recorded at all."
+                "description": "The person whose decision was refused, `human:<id>`. Distinct from the record's own `actor`, which is the runtime: this field is the SUBJECT of the observation, and the record's actor is its author. `^human:` because this event exists only for a human decision; a refusal handed to an agent is not recorded at all. Required unless the refusal is precisely that the runtime could not say who the person was — see the `sender` field and the rule below it.",
+                "$comment": "APRV-324 moved this out of the payload's `required` list and into the conditional rule below, which requires it on every record that does not carry a `sender`."
+              },
+              "sender": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "channel",
+                  "id"
+                ],
+                "description": "SPEC.md §10.3 (amended, APRV-324): the authenticated sender whose decision was refused. Carried on a `sender-unmapped`, `sender-ambiguous` or `sender-key-unavailable` refusal, where it is the only thing the runtime knows about who tapped and the reason the record exists — an operator investigating who tried needs the account — and on any other refusal of a decision whose actor WAS resolved from a sender, where it says which account spent the attention.",
+                "properties": {
+                  "channel": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The surface that observed the sender: `telegram`."
+                  },
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The transport's own account id, as a string, OR the operator's keyed digest of it when `hashed` is true. Raw, a Telegram user id is not a credential: it is visible to everyone in the chat the tap arrived from. Under a keyed mapping the digest is what the operator can act on, because it is exactly the string their `senders` block would carry."
+                  },
+                  "hashed": {
+                    "$ref": "#/$defs/senderHashed"
+                  }
+                },
+                "allOf": [
+                  {
+                    "$ref": "#/$defs/senderHashedImpliesDigest"
+                  }
+                ],
+                "examples": [{ "channel": "telegram", "id": "12345678" }]
+              },
+              "sender_source": {
+                "type": "string",
+                "enum": [
+                  "policy"
+                ],
+                "description": "How the sender became the actor, on a refusal whose actor was resolved. Absent where nothing resolved, which is what a `sender-unmapped` refusal is."
               },
               "decision": {
                 "type": "string",
@@ -1507,6 +1775,276 @@
         }
       }
     },
+    {
+      "$comment": "SPEC.md §10.3/§11.1 (amended, APRV-324): a refused decision names the person it was refused for, UNLESS naming one is exactly what the runtime could not do. Before the sender mapping, every decision surface held one configured human identity and the answer was always available; `sender-unmapped` is the case where a transport authenticated an account the attested policy binds to nobody, and the honest record of it carries the account and no person. Writing the listener's own identity there would have been the false statement the refusal exists to prevent — that the operator's decision was refused, when the operator did not decide. So the requirement is conditional rather than dropped: a record with no `sender` MUST still name the human, which is every refusal the runtime wrote before this rule existed and every refusal on a surface that authenticates no sender.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "audit.decision_refused"
+          },
+          "payload": {
+            "type": "object",
+            "not": {
+              "properties": {
+                "sender": {}
+              },
+              "required": [
+                "sender"
+              ]
+            }
+          }
+        },
+        "required": [
+          "event",
+          "payload"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "actor": {
+                "type": "string",
+                "pattern": "^human:"
+              }
+            },
+            "required": [
+              "actor"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "$comment": "SPEC.md §8 (amended, APRV-355): a human made a gesture on a decision surface that is NOT a decision — a checkpoint signature, a review — and the surface refused it before any verb ran, so nothing else was appended. Found while landing APRV-324 (PR #427): `audit.decision_refused` requires an `action_key` and a `payload.decision` of grant, reject or revoke, and a signature or a review has neither, so recording one of these there would have meant manufacturing both. The cost of recording nothing is that attention spent, and an attempt made by an account the operator did not map, leave no trace in the log at all — only a terminal line and a chat answer.\n\nAUDIT TIER, in the strict sense `audit.decision_refused` set: it grants nothing, mints no token, settles no request, charges no budget, is not sampled, and NO ENFORCEMENT PATH READS IT. It is the runtime's statement about a refusal the runtime made.\n\nThe actor MUST be `^system:`, for the reason `audit.dark_session`'s and `audit.decision_refused`'s are: a record of a refusal authored by either party to it is a record neither party can be held to. The human, when the runtime could name one, is named in the payload; on the refusal where it could not — a transport authenticated an account the attested policy binds to nobody — the payload carries the observed `sender` and no `actor`, on the same conditional terms APRV-324 gave the decision record.\n\nThere is no `action_key` and no `decision`, deliberately. A signature answers for a chain head and a review answers for a sampled record; neither is an action the gate holds a key for, and a field invented to satisfy a schema would be a false statement in a record whose whole purpose is to be true about an attempt.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "audit.gesture_refused"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "required": [
+          "actor",
+          "channel",
+          "payload"
+        ],
+        "properties": {
+          "actor": {
+            "type": "string",
+            "pattern": "^system:",
+            "description": "The runtime. A `human:` or `agent:` actor is refused: the record states that a surface refused a gesture, and the parties to that refusal do not author it."
+          },
+          "channel": {
+            "$ref": "#/properties/channel",
+            "description": "Which surface collected the gesture — `telegram`, `web`, `cli`. Required here for the reason it is required on `audit.decision_refused`: a refusal a reader cannot attribute to a surface is one they cannot go and reproduce, and every decision surface knows its own name."
+          },
+          "payload": {
+            "type": "object",
+            "required": [
+              "gesture",
+              "code"
+            ],
+            "properties": {
+              "gesture": {
+                "enum": [
+                  "checkpoint-signature",
+                  "review",
+                  "review-note"
+                ],
+                "description": "What was attempted. `checkpoint-signature` is a signature over a chain head (§9, APRV-257); `review` is a retrospective verdict on a sampled record (§10.1, APRV-299); `review-note` is that same gesture carrying a human's own words, distinguished because a note is attention spent writing rather than attention spent tapping, and an operator reading this record to decide whether to map an account wants to know which. CLOSED, and additive-only like every other vocabulary here (§11.1 invariant 6): a kind the write boundary refuses is an observation that never reaches a human."
+              },
+              "code": {
+                "enum": [
+                  "sender-unmapped",
+                  "sender-ambiguous",
+                  "sender-key-unavailable",
+                  "policy-not-attested"
+                ],
+                "description": "Why the surface refused, verbatim from the resolution that refused. CLOSED, and exactly the refusals sender resolution can reach before a verb runs: the first three are `CHANNEL_DECISION_REFUSAL_CODES` (`core/sender-identity.ts`), and the last is `ATTESTATION_REFUSAL` (`core/attest.ts`), which fires when the policy declaring the mapping is not the attested one and is therefore not in force. `sender-key-unavailable` (APRV-370) is the policy mapping this channel's senders in the keyed form while the process holds no key: the runtime could resolve NO account, which is a statement about the listener rather than about the person who tapped. `attest-requires-terminal` is not here: it belongs to an attestation tap, which is a decision."
+              },
+              "actor": {
+                "type": "string",
+                "pattern": "^human:",
+                "description": "The person whose gesture was refused, `human:<id>`, when the runtime could name one. Distinct from the record's own `actor`, which is the runtime: this field is the SUBJECT of the observation and the record's actor is its author. Required unless the refusal is precisely that the runtime could not say who the person was — see `sender` and the rule below it."
+              },
+              "sender": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "channel",
+                  "id"
+                ],
+                "description": "SPEC.md §10.3: the authenticated sender the gesture arrived from. The transport's own attribution and nothing the message claimed about itself (§11.1 invariant 4). On `sender-unmapped` it is the whole of what is known about who tried, and the reason the record exists: an operator deciding whether to map an account needs the account.",
+                "properties": {
+                  "channel": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The surface that observed it. `telegram` at v0.1."
+                  },
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The transport's account id, as a string, OR the operator's keyed digest of it when `hashed` is true."
+                  },
+                  "hashed": {
+                    "$ref": "#/$defs/senderHashed"
+                  }
+                },
+                "allOf": [
+                  {
+                    "$ref": "#/$defs/senderHashedImpliesDigest"
+                  }
+                ]
+              },
+              "sender_source": {
+                "enum": [
+                  "policy"
+                ],
+                "description": "How the sender became the actor, when one did. `policy` at v0.1: the attested policy's `senders` mapping."
+              },
+              "message": {
+                "type": "string",
+                "description": "The refusal message, as the person was shown it. A convenience for a reader; `code` is what anything machine-readable branches on."
+              }
+            }
+          }
+        }
+      }
+    },
+    {
+      "$comment": "SPEC.md §10.3/§11.1 (APRV-355), the same conditional APRV-324 gave `audit.decision_refused`: a refused gesture names the person it was refused for, UNLESS naming one is exactly what the runtime could not do. A record with no `sender` MUST still name the human, which is every refusal on a surface that authenticates no sender.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "audit.gesture_refused"
+          },
+          "payload": {
+            "type": "object",
+            "not": {
+              "properties": {
+                "sender": {}
+              },
+              "required": [
+                "sender"
+              ]
+            }
+          }
+        },
+        "required": [
+          "event",
+          "payload"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "payload": {
+            "type": "object",
+            "properties": {
+              "actor": {
+                "type": "string",
+                "pattern": "^human:"
+              }
+            },
+            "required": [
+              "actor"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "$comment": "SPEC.md §8 (amended, APRV-378): something other than this gate answered a question this gate exists to ask. The first instance is Codex's server-side auto-reviewer (`docs/codex-app-server-bridge.md`, question 3): a model call can resolve an approval before `approval codex bridge` is asked, and the client is told afterwards through an `item/autoApprovalReview` notification. No existing type carries the fact. `audit.dark_session` is the sweep over activity with no records beside it; `audit.decision_refused` is a human gesture the gate would not take; `audit.gesture_refused` (APRV-355) is a gesture that is not a decision at all. This one is none of those: the question existed, the gate would have asked it, and somebody else answered first.\n\nThe NAME is general because the instance will not be the last. `source` is a closed enum whose first member names the Codex auto-reviewer, and a second party gains a member rather than a type.\n\nAUDIT TIER, on the strict terms `audit.decision_refused` and `audit.gesture_refused` set: it grants nothing, mints no token, settles no request, charges no budget, is not sampled, and NO ENFORCEMENT PATH READS IT. `approval doctor` reads it, which is a diagnosis rather than an enforcement: the row it feeds authorizes nothing and refuses nothing.\n\nThe actor MUST be `^system:`, for the reason `audit.dark_session`'s and `audit.gesture_refused`'s are: a record of an event authored by either party to it is a record neither party can be held to. Here both parties are machines, and neither the harness that pre-empted the question nor the agent whose action it was may author the note that says so.\n\n`verdict` is OPTIONAL and carries the other party's word verbatim when the notification stated one. It is not defaulted: a record that said `accept` because nothing said otherwise would be this runtime inventing another party's decision, which is the one thing a record about another party's decision may not do. Its absence is a fact about the notification.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "audit.question_preempted"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "required": [
+          "actor",
+          "payload"
+        ],
+        "properties": {
+          "actor": {
+            "type": "string",
+            "pattern": "^system:",
+            "description": "The runtime. A `human:` or `agent:` actor is refused: the record states that something else answered a question, and neither party to that may author the statement."
+          },
+          "payload": {
+            "type": "object",
+            "required": [
+              "source",
+              "question"
+            ],
+            "properties": {
+              "source": {
+                "enum": [
+                  "codex-auto-reviewer"
+                ],
+                "description": "Who answered instead of the gate. CLOSED, and additive-only like every other vocabulary here (§11.1 invariant 6). `codex-auto-reviewer` is Codex's server-side guardian reviewer, whose answer is a genuine model call (`codex-rs/core/src/guardian/decision.rs`) and which runs before the client path. A second party gains a member here rather than an event type of its own."
+              },
+              "question": {
+                "type": "object",
+                "required": [
+                  "id"
+                ],
+                "description": "The question that was answered, as the OTHER PARTY identified it. Its own identifiers and nothing this runtime minted: a record about somebody else's decision names it in their terms, or a reader cannot go and find it on their side.",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The other party's identifier for the question. Codex's `itemId` on the item-based API."
+                  },
+                  "method": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The notification that disclosed it, verbatim: `item/autoApprovalReview/started` or `item/autoApprovalReview/completed` at v0.1."
+                  },
+                  "thread": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The other party's session identifier, where the notification named one. Codex's `threadId`."
+                  },
+                  "turn": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "The other party's turn identifier, where the notification named one. Codex's `turnId`."
+                  }
+                }
+              },
+              "verdict": {
+                "type": "string",
+                "minLength": 1,
+                "description": "The verdict the other party reached, verbatim in their own vocabulary and never translated into this project's. Absent when the notification stated none, which is a fact about the notification rather than a default."
+              },
+              "detail": {
+                "type": "string",
+                "description": "The runtime's own one line about what it did next. A convenience for a reader; nothing branches on it."
+              }
+            }
+          }
+        }
+      }
+    },
     {
       "$comment": "SPEC.md §5.2 (amended, APRV-214), 'The open window': a person opening the harness gate on themselves so the gate can be debugged from inside. The actor MUST be `^human:`, in the schema as well as in `core/gate-window.ts`, for the reason attestation refuses an agent: this is the one act that suspends the policy, and an agent able to author it could authorize its own next command. The window's state lives here and in no file, so what a reader derives is derived from a verified chain and nothing else. Expiry is `ts` plus `duration`, and a record claiming an `expires_at` beyond that reads as the shorter of the two: the field is a convenience for a human reading the log, never the authority.",
       "if": {
@@ -1806,6 +2344,54 @@
           }
         }
       }
+    },
+    {
+      "$comment": "SPEC.md §5.2/§8/§10.1 (amended, APRV-338): a human's sign-off on the exact bytes of one PROTECTED PATH whose edits classify `policy.edit` or a `policy.edit.*` sub-class — a specification, an agent instruction file, CI configuration, a document a policy's `protected_paths` widened the surface with. The sibling of `gate.organ.attested` and deliberately a different type, because the two answer about different surfaces under different rules: an organ has no grant available to it at all, while a protected path does, and the after-the-fact checker of §10.1 prefers the grant's hunk evidence and reads this record only when no grant covers the change. Whole-file evidence, and weaker than a hunk grant for exactly that reason: it says a human read this file at these bytes and stands behind them, not that they saw a particular line change. The actor MUST be `^human:`, in the schema as well as in `core/attest.ts`: a record an agent could write would let the party under oversight ratify its own text. Both payload fields are computed by the runtime — the digest from the file's bytes, the path normalized — and the caller supplies neither. Gate-typed (`gate.` prefix), so `ts` is stamped at the write boundary.",
+      "if": {
+        "type": "object",
+        "properties": {
+          "event": {
+            "const": "gate.path.signed_off"
+          }
+        },
+        "required": [
+          "event"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "required": [
+          "actor",
+          "payload"
+        ],
+        "properties": {
+          "actor": {
+            "type": "string",
+            "pattern": "^human:"
+          },
+          "payload": {
+            "type": "object",
+            "required": [
+              "path",
+              "sha256"
+            ],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 512,
+                "pattern": "^[^/\\\\][^\\\\]*$",
+                "description": "The signed-off file's REPOSITORY-RELATIVE, `/`-separated path, for example `SPEC.md`. Relative and never absolute, for the reason `organ_path` is: a permanent record must not leak the writer's home directory and must name the same file on the machine that later reads it. That the path actually classifies `policy.edit` or a `policy.edit.*` sub-class, and is neither the policy file nor a `policy.core` surface, is the runtime's check (`core/attest.ts`), as is the refusal of `..`; a schema sees one record and constrains the shape."
+              },
+              "sha256": {
+                "type": "string",
+                "pattern": "^[a-f0-9]{64}$",
+                "description": "SHA-256 (lowercase hex) of the file's exact bytes at the moment of sign-off, computed by the runtime. Bytes, not text, so a file differing by trailing whitespace is a different file and a record about it is not a record about this one. The caller has no parameter for this value — one who could supply it could sign off on bytes nobody read."
+              }
+            }
+          }
+        }
+      }
     }
   ]
 }