CTRLRun · arpanghoshal · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026 · Sep 12, 2026
@@ -124,12 +124,15 @@ jobs:
           # G13 is N/A on SQLite, the action's default store: SQLite has no clock of its own
           # to diverge from; G15 is N/A because neither document declares `max_attempts`.
           # G16 is graded on both: verify brings its own precondition provider (SPEC-v0.7 §8.9).
-          # G18 likewise since v0.8 item 2, which supplies its own approver identity: whether
+          # G17 is N/A on both since v0.8 item 3: neither document names an
+          # `approver_role`, which is a statement about what the operator wrote
+          # (SPEC-v0.8 §3.5, §11.7). G18 is graded since item 2, which supplies its
+          # own approver identity: whether
           # an operator configured one is a fact about their application and never an N/A
           # reason here (SPEC-v0.8 §11.7). Both counts moved by one when it landed.
-          test "$AUTHORITY_NA" = "2"
+          test "$AUTHORITY_NA" = "4"
           test "$TEMPLATES" = "verified 9/9"
-          test "$TEMPLATES_NA" = "8"
+          test "$TEMPLATES_NA" = "10"
           test -s verify-badge.json
           test -s verify-report.json
           test -s verify-report.xml

@@ -11,6 +11,139 @@ any change to one appears here.
 
 ### Added
 
+- **Break-glass is a grant, and there is no flag** (`docs/SPEC-v0.8.md` §5). An incident needs
+  authority nobody was granted in advance. The wrong answer is a setting: a setting leaves no
+  record, expires never, cannot be revoked and cannot be narrowed. `authority.py` already has
+  grants that are all five, so break-glass is a delegation beneath an **envelope** the policy
+  declared in advance.
+
+  ```yaml
+  authority:
+    break_glass:
+      incident-payments:
+        subject: {agent: "oncall-*"}     # who a grant opened here may be FOR
+        actions: ["payments.*"]
+        constraints: {amount_lte: 50000}
+        max_ttl: PT4H                    # the longest expiry a grant beneath it may carry
+        controls: [incident-response]    # whose approver_role gates who may OPEN it
+  ```
+
+  ```
+  ctrlrun break-glass --envelope incident-payments --file grant.yaml --reason "INC-4412"
+  ```
+
+  **The envelope decides nothing, by construction.** It lives in `Authority.envelopes`, a mapping
+  separate from `grants`, because the candidate set is every entry of `grants` unconditionally: an
+  envelope living there would decide actions, which is the opposite of what it is for. The test
+  asserts it is absent from the candidate set rather than merely unmatched.
+
+  **It is covered by the policy hash, `max_ttl` included.** The argument for declaring the widest
+  authority an incident can reach in a file is that somebody reviewed it *before* the incident, and
+  that argument is only true if widening it moves every receipt.
+
+  **There is no `--as`.** Whoever opens one is the principal the deployment's approver identity
+  resolves, gated by the envelope's `controls:`; a deployment that names no approver identity
+  cannot open one at all. An assertion typed at a shell is exactly what break-glass must not
+  accept.
+
+  **What it is afterwards**: recorded, with `created_via: break-glass`; expiring, and bounded by
+  `max_ttl` from the moment it was opened; revocable, and revoking it stops everything beneath it;
+  attenuable, obeying `child ⊆ parent` on every dimension. A setting has none of those.
+
+  **`Receipt.authority_grant_id`** now names the grant that decided the action, for **every**
+  action decided by authority and not only under break-glass. A field exercised only on the rare
+  path is one nobody notices breaking.
+
+  `created_via` gains its third value, which is a public change rather than an addition: the
+  vocabulary is a closed set and a record carrying an unknown value is unreadable, which answers
+  `authority_unreadable` for every action in the deployment. It moves with every reader in one
+  commit.
+
+  No guarantee id. The roadmap assigned five to v0.8 and G22 to G24 to v0.9, so inventing a sixth
+  would collide or renumber, and a renumber is the maintainer's change. Its evidence is its tests,
+  and one of them greps the shipped package for sixteen names a flag would be spelled as.
+
+- **M-of-N approvals** (`docs/SPEC-v0.8.md` §4). An action may require more than one yes, and what
+  the threshold counts is **distinct verified principals**: a second answer from a principal that
+  already answered is recorded, moves that entry's `granted_at`, and does not move the count.
+
+  ```yaml
+  schema: ctrlrun.policy/v6
+  actions:
+    payments.refund:
+      decision: approve
+      approvals_required: 2
+  ```
+
+  **The count is decided where the row is written, on all three stores**, and never by a read
+  followed by a write: SQLite counts inside its `BEGIN IMMEDIATE` transaction, Postgres
+  compare-and-sets on the approver list it read and retries, and the in-memory store holds its
+  lock. Two processes answering at the same instant produce two approvers or one, never a
+  threshold reached twice.
+
+  **A yes that cannot be attributed does not count.** `approvals_required` above 1 in a deployment
+  that names no approver identity is a denial, not a silent downgrade to one approval: the kernel
+  cannot tell two anonymous yeses apart, so it refuses rather than counting them. `ctrlrun approve`
+  records no verified approver and therefore never counts toward a threshold, which the CLI says
+  at the moment it is used rather than leaving to be discovered.
+
+  `ApprovalStore.grant_approval` now returns `Approval | None`, where `None` means **recorded and
+  still short of N**. Nothing is granted, no `APPROVAL_GRANTED` event is written, and a consume
+  attempted below the threshold is refused as `pending` with nothing reserved.
+
+  Needs `ctrlrun.policy/v6`. `ctrlrun verify` grades **G19** under `ctrlrun.guarantees/v4`, `N/A`
+  where every action in the document takes one approval.
+
+- **Entitlement from the control registry** (`docs/SPEC-v0.8.md` §3). A control may now name the
+  role that answers for it, and an approval whose recorded entitlement does not cover the roles
+  the request pinned is refused, with the control named in the message, the exception and the
+  `APPROVAL_INVALIDATED` event.
+
+  ```yaml
+  schema: ctrlrun.policy/v6
+  controls:
+    card-data-handling:
+      title: Cardholder data changes are approved by a named owner
+      approver_role: payments-owner
+  ```
+
+  **CTRLRun does not interpret the role.** It does not know what `payments-owner` means, does not
+  check that such a role exists anywhere, and makes no compliance claim on the strength of one,
+  exactly as it does not interpret `source:`. What changed about `SPEC-v0.6.md` §7.3's
+  "attribution, not prevention" is one sentence: a control still decides no *action*, and now
+  decides **who may answer an approval the decision already required**.
+
+  **Omission is not entitlement, and a control naming no role gates nobody.** Two sentences that
+  mean opposite things: a principal whose claims lack the role is not entitled, because a missing
+  claim is a statement about a person and the kernel refuses to invent one; a control with no
+  `approver_role` gates nobody, because a missing role is a statement about the operator's
+  document and inventing one there would refuse every approval in every deployment that has
+  controls and has not heard of v0.8.
+
+  **Roles are matched byte for byte**, in both claim shapes. No case folding, no trimming, no
+  prefix matching and no pattern grammar: a wildcard in a role would be an entitlement nobody
+  wrote. Where an evaluation cites several controls, **every** required role must be held, because
+  any-of lets the weakest control in the set decide who may answer.
+
+  **`ClaimValue` gains a tuple of strings**, amending `SPEC-v0.3.md` §2.1. A roles claim is a JSON
+  array at every issuer anybody deploys, and the old rule meant such a claim arrived *absent*, so
+  its holder was silently unentitled. `JWTIdentityProvider` carries an array-of-strings claim now
+  instead of dropping it, and says so at WARNING rather than DEBUG when it drops anything else it
+  was asked to carry. Safe for hashes: `v0.3 §2.2` keeps claims out of an action's canonical form.
+
+  **The check is bounded and the bound is stated.** What the kernel refuses is an approval whose
+  *recorded* entitlement does not cover the role; what entitled it was decided where the credential
+  was verified, which is the operator MCP server (`ctrlrun mcp-operator --approver-roles-claim`)
+  and an embedding application. `docs/SPEC-mcp-operator.md` §4.3 and §10 are amended to say that,
+  and §4.3 now carries a three-row table instead of one sentence, because the sentence covered
+  two unconfigured cases that behave in opposite ways: a control naming no role admits any
+  verified human, and a control naming a role in a deployment with no claim to read roles from
+  refuses **everyone**. The server warns about the second at startup rather than at the first
+  refusal.
+
+  Needs `ctrlrun.policy/v6`. `ctrlrun verify` grades **G17** under `ctrlrun.guarantees/v4`, `N/A`
+  with a reason that is true of a document naming no approver role.
+
 - **The approver is a principal** (`docs/SPEC-v0.8.md` §2, §4.1). `Approval.approver` is a string
   whose only check is that it is not empty, and `adapter.py` has always conceded what that string
   often is: a channel, wherever the framework's primitive does not identify a person. A deployment

@@ -172,6 +172,7 @@ Then, in this order:
 | The provider returned `None` | Refused, `-41007`. A decline is a refusal here, with no `context()` to fall back to and nothing that may be backfilled |
 | It returned a `Principal` with `expires_at` set and now past it | Refused, `-41014` `ctrlrun.principal_expired`. `v0.3 §2.3`'s check, applied at the one entry point that never reaches `Control.execute` |
 | It returned a `Principal` with `user is None` | Refused, `-41013` `ctrlrun.not_a_human` (§3.2) |
+| It returned a `Principal` the cited control's `approver_role` does not cover | Refused, `-41015` `ctrlrun.not_entitled`, with the control and the role named (`SPEC-v0.8.md` §3.7). Its own code for `-41014`'s reason: the answer tells a human which role they were missing, and `-41007` deliberately says nothing about why |
 | Otherwise | The write proceeds, attributed to it (§5.4) |
 
 **No receipt and no events for any row above.** `v0.3 §3.2`'s last paragraph is the rule: a
@@ -240,9 +241,28 @@ answered yes to one exact `action_hash`; it becomes permission only when `Contro
 consumes it, and `Control.execute` evaluates the principal's expiry, then authority, then policy,
 then the approval, in that order (`v0.3 §4.3.1`), every time, for the action the grant names. A
 second authority evaluation here would be evaluating the *approver's* authority against the
-*agent's* action, which is a different question that this release does not answer (see §10:
-authenticating the approver's entitlement to approve is not in scope, and the honest place for it
-is a separation-of-duties model that does not exist yet).
+*agent's* action, which is a different question and one this document still does not answer.
+
+**Amended by `SPEC-v0.8.md` §3, and the amendment is narrower than it sounds.** Since v0.8 this
+server checks the approver's **entitlement**: where the deployment names an approver identity and
+the cited control names an `approver_role`, an answer from a credential that does not carry that
+role is refused here, with the control named, and the roles the answer satisfied are recorded on
+the approval row. That is not an authority evaluation and it is not separation of duties: it is
+one string from the operator's own control registry compared against one claim on a verified
+credential, and CTRLRun interprets neither.
+
+**The unconfigured cases are two, they are not the same, and the earlier wording here stated
+one of them backwards.** `SPEC-v0.8.md` §3.5's rule is that omission is not entitlement and it is
+not refusal either, and which one a deployment gets depends on which half is missing:
+
+| What the deployment configured | What this server does |
+|---|---|
+| No approver identity, or a cited control naming no `approver_role` | The paragraph above is unchanged and describes the deployment: any human whose credential the provider verifies can answer any pending request |
+| A control naming an `approver_role`, and no `--approver-roles-claim` | **Every answer to that request is refused**, here and again at consumption. No claim can be read, so no role is held, and half a check fails closed (`SPEC-v0.8.md` §3.4). The server warns at startup rather than at the first refusal |
+| A control naming an `approver_role`, and a claim the credential does not carry | That answer is refused, `-41015`, with the control and the role named |
+
+Both of the first two are true of real configurations, which is why both are here, and the
+difference between them is the whole of §3.5.
 
 `resolve` is the same shape: it states what happened at a remote. It is `v0.1 §5.2`'s human
 authority, and the store already refuses to apply it to anything but an `AMBIGUOUS` record.
@@ -429,6 +449,7 @@ enforcing, and answering one changes nothing in the world.
 | A write tool with no principal, a declined or rejected credential | HTTP 403, `-41007` |
 | A write tool whose principal has no `user` | HTTP 403, `-41013` |
 | A write tool whose principal has expired | HTTP 403, `-41014` |
+| `approve` whose principal lacks a role a cited control requires | HTTP 403, `-41015` |
 | `approve`/`deny` on an unknown, answered or expired request | HTTP 200, `-41003`, with the store's reason |
 | `resolve` on a record that is not `AMBIGUOUS`, or an unknown key | HTTP 200, `-41003`, with the store's reason |
 | `resolve` with a blank reason | HTTP 200, `-32602` |
@@ -626,6 +647,7 @@ neither is reachable from the gateway.
 |---|---|---|
 | `-41013` | `ctrlrun.not_a_human` | 403 |
 | `-41014` | `ctrlrun.principal_expired` | 403 |
+| `-41015` | `ctrlrun.not_entitled` | 403 |
 
 Reused unchanged: `-41003` `ctrlrun.approval_denied` for a store refusal about an approval or an
 effect, and `-41007` `ctrlrun.no_principal`.
@@ -694,13 +716,22 @@ did before the move to `ctrlrun.reporting`, exit code included.
 
 Everything `v0.6 §11` excludes, plus:
 
-- **Authenticating the approver's *entitlement*.** This server authenticates *who* is answering;
-  it does not check that they were allowed to. `v0.3 §13` and `v0.5`'s do-not-build list already
-  exclude authenticating the approver, separation of duties, M-of-N and break-glass, and nothing
-  here changes that. The honest statement is in §4.3: any human whose credential the provider
-  verifies can answer any pending request, exactly as any human who can run `ctrlrun approve`
-  can today. **This is attribution, not authorization**, and no document may describe it as the
-  latter.
+- **Authenticating the approver's *entitlement*.** ~~This server authenticates *who* is
+  answering; it does not check that they were allowed to.~~ **Amended by `SPEC-v0.8.md` §3**,
+  and the strikethrough is deliberate: this line was true of every release up to 0.7.0, and a
+  reader of an older deployment's documentation should be able to see which sentence applied.
+
+  What is true now: where an approver identity and an `approver_role` are configured, this server
+  **does** check entitlement, refuses an answer the credential is not entitled to give, and
+  records what the answer satisfied. Where they are not, the old sentence still holds exactly:
+  any human whose credential the provider verifies can answer any pending request, exactly as any
+  human who can run `ctrlrun approve` can.
+
+  **What is still out of scope**: separation of duties as a model, and evaluating the approver's
+  *authority* against the agent's action. M-of-N and break-glass arrive with v0.8's items 4 and 5
+  and are not this server's. And the check is bounded the way `SPEC-v0.8.md` §3.8 bounds it: what
+  it compares is one operator-written string against one claim, and what the kernel later refuses
+  is an approval whose **recorded** entitlement does not cover the role.
 - **stdio transport.** An MCP server launched over stdio by the assistant has no credential to
   verify — the process is whatever the client started, and every candidate identity is asserted
   by it. That is `--principal-from-client-info` (`v0.3 §8.1`) in a fourth costume, and it is the
@@ -729,6 +760,7 @@ Everything `v0.6 §11` excludes, plus:
 | A write tool, credential declined or rejected | `-41007`, store unchanged |
 | A write tool, credential names no human | `-41013`, store unchanged |
 | A write tool, credential expired | `-41014`, store unchanged |
+| `approve`, credential missing a required `approver_role` | `-41015`, store unchanged: no grant, no event, no partial row |
 | `resolve` with no reason | `-32602`, store unchanged |
 | An unknown tool, an unknown method, a bad argument | A JSON-RPC error, store unchanged |
 | Anything the store refuses | The store's refusal, unchanged. Store unchanged, **except** that answering a lapsed request records the lapse (§4.2) |