approval-md 0.3.0 → 0.4.1

package/schema/policy.schema.json

@@ -135,19 +135,43 @@
                     "12345678",
                     "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
                   ]
+                },
+                "edgeos": {
+                  "type": "string",
+                  "minLength": 1,
+                  "pattern": "^(?:[A-Za-z0-9][A-Za-z0-9._-]{0,127}|hmac-sha256:[0-9a-f]{64})$",
+                  "description": "The EdgeOS account this person decides from, in one of two forms (SPEC.md §5.2/§10.3, APRV-455, on the ground APRV-324 laid for `telegram`).\n\nRAW: the stable human id the EdgeOS identity service returns from `/humans/me` for the session the person authenticated in, as a string. The runtime treats it as OPAQUE and compares it byte for byte; the grammar admits what such an id is made of (an ASCII letter or digit, then up to 127 letters, digits, `.`, `_` or `-`), which covers a UUID and a decimal id alike. It holds no `:` and no whitespace, so a raw id can never be mistaken for the keyed form and can never contain the separator the runtime's sender index uses. Never an email address or a display name: those are chosen or changed by the person, and a mapping keyed on one would transfer an identity with an edit.\n\nKEYED: `hmac-sha256:<64 lowercase hex>`, the HMAC-SHA-256 of that same id under the operator-held `APPROVAL_SENDER_KEY`, exactly as for `telegram` and for the same reason: a published policy and a published log otherwise disclose the account.\n\nThe id reaches the runtime through `approval channel relay`, whose authenticated caller (the operator's control plane, holding `APPROVAL_RELAY_SECRET`) reports which EdgeOS session made the gesture. The daemon trusts that report the way it trusts the Telegram Bot API's `from.id`: it is operator trust in a relay, stated as such, and the resident cannot choose the id the relay attributes to them.",
+                  "examples": [
+                    "4f1c2a9e-7b3d-4e8a-9c21-5d6e7f8a9b0c",
+                    "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
+                  ]
                 }
               },
               "examples": [
                 { "telegram": "12345678" },
                 {
                   "telegram": "hmac-sha256:3f2a9c11b4d7e6085a1c2f9d8e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a"
-                }
+                },
+                { "telegram": "12345678", "edgeos": "4f1c2a9e-7b3d-4e8a-9c21-5d6e7f8a9b0c" }
               ]
             }
           }
         }
       }
     },
+    "daemons": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "SPEC.md §5.2 (amended, APRV-383): the daemon instance ids permitted to append to this log. An ALLOWLIST, and the counterpart of `approvers` one layer down: that key says which humans may decide, this one says which daemon processes may write the records of those decisions down.\n\nIt exists for the hosted case (`design/hosted-daemon-identity.md`): when one party runs the daemon for another, records the daemon appends carry `daemon` (see `event.schema.json`) naming the instance that wrote them, and this list is how the tenant's own attested policy states which of them it expects. A daemon whose id this list does not name is refused AT THE WRITE BOUNDARY with `daemon-not-allowed` and writes nothing.\n\nABSENT means NO RESTRICTION, not an empty list: a policy that never declares the key behaves exactly as every policy written before it existed, and the daemon-written records still carry their id. An empty array is a policy that admits no daemon at all, which is a thing an author may say and the runtime will enforce.\n\nWhat being LISTED buys is nothing (SPEC.md §11.1 invariant 4). The id is self-reported by the writing process, so it may only ever cost a daemon the ability to write: no verdict, autonomy, budget, floor, sampling draw, token or TTL reads this key or the record field, and a hostile host holding the tenant's log handle is not what this defends against. What it catches is a daemon started against the wrong tenant's log, a second daemon nobody meant to leave running, and a rebuilt container whose id changed, each of which used to write records indistinguishable from the intended daemon's.\n\nIt is a top-level key rather than a member of the `daemon` block below, and the distinction is worth the two names: `daemon` (singular) is how THIS daemon reads a log it already may write, every key in it a latency setting whose strictest value is the default, while `daemons` (plural) is an ENFORCEMENT key deciding WHICH daemons may write at all. Read only from an ATTESTED policy, like every other fact a refusal is derived from.",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "pattern": "^[a-z0-9][a-z0-9._-]*$",
+        "description": "One daemon instance id, in the same grammar the `daemon` record field carries: lowercase letters, digits, `.`, `-` and `_`, starting with a letter or digit. Either an id the operator declared in that daemon's launch environment through `APPROVAL_DAEMON_ID`, or the derived `daemon-<instance id>` form that `approval status` and `approval doctor` print for the instance they are run against."
+      },
+      "examples": [["daemon-3f2a9c11"], ["village-goa-1", "village-goa-2"]]
+    },
     "classes": {
       "type": "object",
       "additionalProperties": false,
@@ -213,7 +237,7 @@
     "daemon": {
       "type": "object",
       "additionalProperties": false,
-      "description": "APRV-217 (docs/proposals/incremental-prefix-proof.md): how the long-lived readers of this log prove a cached prefix before they reuse it. Read by `approval daemon run` and `approval up` and by nothing else: one-shot processes, the Claude Code hook included, always prove in full, and `approval log verify` and `approval doctor` never use the cache at all. Every key here is a LATENCY setting whose strictest value is the default, so a policy that omits the block, or the whole block, behaves exactly as the runtime did before it existed.",
+      "description": "APRV-217 (docs/proposals/incremental-prefix-proof.md): how the long-lived readers of this log prove a cached prefix before they reuse it. Read by `approval daemon run` and `approval up` and by nothing else: one-shot processes, the Claude Code hook included, always prove in full, and `approval log verify` and `approval doctor` never use the cache at all. Every key here is a LATENCY setting whose strictest value is the default, so a policy that omits the block, or the whole block, behaves exactly as the runtime did before it existed. Not to be confused with the top-level `daemons` list above (APRV-383), which is an enforcement key naming WHICH daemon instances may append to this log; this block is how a daemon that may already write reads.",
       "properties": {
         "read_proof": {
           "type": "string",
@@ -362,6 +386,58 @@
           "$ref": "#/$defs/promptRows",
           "description": "Visibility DOWN: the row never renders on this channel. Refused for the rows required for a decision — `action_key`, `class`, `command_breakdown`, `protected_path`, `policy_diff`, `policy_load` — and refused at policy load with the machine-readable keyword `prompt-row-required`, which fails the whole policy closed. `payload_hash` is NOT among them because the bound hash is stated inside the canonical block on every channel, so hiding the row removes a duplicate rather than the binding. Naming one row in both `always` and `hide` is refused rather than resolved by precedence: an author who wrote both believes one of them, and picking for them would be a guess.",
           "examples": [["provenance", "chain", "requested_ts"]]
+        },
+        "style": {
+          "type": "string",
+          "enum": ["technical", "minimal"],
+          "default": "technical",
+          "description": "SPEC.md §5.2/§10.3 (APRV-489): how this channel lays out a prompt. `technical`, the default and what an absent key means, is the card every earlier build sent, byte for byte. `minimal` is a short card in plain words: a headline the runtime computes from the class, the payload's own words quoted from the bound bytes, a deadline in plain words, and the whole technical card, canonical rendering included, collapsed inside the same message as the Approve and Deny buttons (SPEC.md §10.3, amended APRV-489). Only Telegram draws it in this release; on `web` and `cli` the key is validated and IGNORED, which shows more than was asked for and never less. A request the minimal card cannot draw honestly (an opaque payload without a `say` declaration naming every key, an attestation, a policy edit, a digest, a truncated payload, an abnormal health row, a card over the message limit) is sent as the technical card. Review cards never change. The enum is closed: an unknown style fails validation, which fails the policy closed to all-`manual`.",
+          "examples": ["minimal"]
+        },
+        "say": {
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*(?:\\.[a-z0-9][a-z0-9_-]*)*$" },
+          "additionalProperties": { "$ref": "#/$defs/promptSay" },
+          "description": "SPEC.md §5.2 (APRV-489): what the minimal card says about a class, keyed by EXACT class name (no wildcard: one friendly phrase must never stand for several classes). Operator text the approver attests, never agent text. Read only under `style: minimal`.",
+          "examples": [
+            {
+              "digest.share": {
+                "does": "share a note about you",
+                "quote": { "scope": "Shared with", "expires_at": "Until", "text": "Note", "digest_id": null },
+                "note": "none"
+              }
+            }
+          ]
+        }
+      }
+    },
+    "promptSay": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "SPEC.md §5.2 (APRV-489): one class's minimal-card declaration. `does` is required for a class core does not phrase itself and refused for one it does, or for a class the command classifier emits (checked at load). It is drawn only over an opaque payload: over a command, a file change or an email the runtime draws its own kind phrase.",
+      "properties": {
+        "does": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "description": "The plain-words verb phrase the headline completes: `Your agent wants to <does>`. Starts with a letter; no line break, sentence punctuation (. ! ? … : ;), markup or ⚠ (checked at load). Not allowed for a class core phrases itself or a class the command classifier emits (`prompt-say-kind`). Drawn only over an opaque payload: over a command, a file change or an email the runtime's kind phrase is drawn instead and the decision record notes `say_does_ignored`. The runtime chooses the entry by the exact class the log records."
+        },
+        "quote": {
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1, "maxLength": 64 },
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string", "maxLength": 24 },
+              { "type": "null" }
+            ]
+          },
+          "description": "The closed field set for an OPAQUE payload: every top-level key the payload may carry, mapped to the label its value is quoted under (`\"\"` for no label), or `~` for a key known and deliberately left off the simple card (the card then names it under the quotations). At least one key must be shown (checked at load). A payload carrying any key this map does not name is sent as the technical card. Ignored for command, file-change and email payloads, whose excerpt is built in."
+        },
+        "note": {
+          "type": "string",
+          "enum": ["summary", "none"],
+          "default": "summary",
+          "description": "Whether the agent's own summary is shown, labelled as the agent's and as not checked: `summary` (the default) or `none`."
         }
       }
     },
@@ -402,9 +478,9 @@
     },
     "senderChannel": {
       "type": "string",
-      "enum": ["telegram"],
-      "description": "SPEC.md §10.3 (amended, APRV-324): a channel whose transport attributes a gesture to an account id, and therefore the only kind of channel an `approvers.<id>.senders` entry may name. `telegram` qualifies because the Bot API reports `callback_query.from.id`, which the sender cannot choose. `web` and `cli` are deliberately absent: an unauthenticated form post names nobody and a local process names whoever runs it, so a sender mapping for either would be a binding the runtime cannot check and an identity key the channel cannot support.",
-      "examples": ["telegram"]
+      "enum": ["telegram", "edgeos"],
+      "description": "SPEC.md §10.3 (amended, APRV-324; widened, APRV-455): a channel whose transport attributes a gesture to an account id, and therefore the only kind of channel an `approvers.<id>.senders` entry may name. `telegram` qualifies because the Bot API reports `callback_query.from.id`, which the sender cannot choose. `edgeos` qualifies on the same ground: the gesture arrives through `approval channel relay`, authenticated by a shared secret from the daemon's launch environment, from a control plane that attributes it to the EdgeOS `/humans/me` id of the session the person signed in with, which the person cannot choose either. In both cases the daemon trusts the relay's report of who acted, and that is operator trust (APRV-422: no hosted service has authority over decisions; the relay carries a person's gesture and decides nothing). `web` and `cli` are deliberately absent: an unauthenticated form post names nobody and a local process names whoever runs it, so a sender mapping for either would be a binding the runtime cannot check and an identity key the channel cannot support.",
+      "examples": ["telegram", "edgeos"]
     },
     "classPattern": {
       "type": "string",
@@ -415,7 +491,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["autonomy"],
-      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form may add rates, `allow_irreversible`, `approvers` and `limits`. Both are this one shape — `autonomy` is always REQUIRED, since a rule without it cannot decide anything, and unknown keys are rejected so a typo'd constraint is never silently ignored.",
+      "description": "SPEC.md §5.1: a class rule. The shorthand form is `{ autonomy }` alone; the full form may add rates, `allow_irreversible`, `agent_may_request`, `approvers` and `limits`. Both are this one shape — `autonomy` is always REQUIRED, since a rule without it cannot decide anything, and unknown keys are rejected so a typo'd constraint is never silently ignored.",
       "allOf": [
         {
           "$comment": "SPEC.md §5.2 (amended, APRV-127): `live_rate` belongs to `supervised-live` and to nothing else. Required there, because a live mode with no fraction declares a control without saying how much of it runs, and the runtime would have to invent the number an author did not write. Forbidden everywhere else, because a rate sitting on a `manual`, `supervised-retro` or `autonomous` rule is a fraction its author believes is in force that nothing reads — the same silent no-op this schema's closed shape exists to prevent. APRV-185 adds `human-only` to that everywhere-else, and the `else` branch below already carries it with no new clause: a level whose actions no agent may take has no fraction of them to gate, so a `live_rate` written there is a control its author believes is running over a population of size zero.",
@@ -467,6 +543,22 @@
               }
             }
           }
+        },
+        {
+          "$comment": "SPEC.md §5.2 (amended, APRV-445): `agent_may_request: true` opens the `propose` verb to a class an operator declared, so the level it sits on must be one an agent may ask about. Refused on `human-only` as a load error: a human-only class is inert to agents (SPEC.md §11.1 invariant 9), and a flag saying an agent may file a request for one is a door the gate would only slam. False is admitted everywhere as the explicit spelling of the default.",
+          "if": {
+            "type": "object",
+            "properties": { "agent_may_request": { "const": true } },
+            "required": ["agent_may_request"]
+          },
+          "then": {
+            "type": "object",
+            "properties": {
+              "autonomy": {
+                "enum": ["supervised-live", "supervised", "supervised-retro", "autonomous", "manual"]
+              }
+            }
+          }
         }
       ],
       "properties": {
@@ -480,6 +572,10 @@
           "type": "boolean",
           "description": "SPEC.md §5.2/§7 (amended, APRV-317): explicit permission for truthful `reversible: false` actions matching this rule to retain its nonmanual autonomy. Omission or false preserves the manual floor. Every equally most-specific matching rule must say true; defaults and action metadata cannot supply it."
         },
+        "agent_may_request": {
+          "type": "boolean",
+          "description": "SPEC.md §5.2 (amended, APRV-445): whether an agent may open a request in this class with `approval propose`, naming the class itself and carrying its payload inline. Absent and false mean no. It is read two ways and only these two: on a key that names the class EXACTLY, and on a declared family key `<prefix>.*` the class falls under. `propose` additionally requires the class to be an exact key of `classes`, so a wildcard rule alone never makes a class proposable; the exact key's own value wins when it states one, and otherwise the most specific family that states one decides. Adding or changing it is a policy edit like any other and takes a human re-attestation, which voids pending requests (`policy-drift`)."
+        },
         "approvers": {
           "type": "array",
           "minItems": 1,