change_requests 0.2.2 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 205a020929c71027848bc891897a26676a96fbc2c77a6d2e32aa5cedc577109c
-  data.tar.gz: 172b2e90ff436bd10e42e5a30eb18052b65b20bf660156efec238b58aa58abf5
+  metadata.gz: 7790d14f78ffa0b667712d827db6cc77d527dd9f733582b95b0a43ca4372d156
+  data.tar.gz: 21b70a37fe29a796e855571f82901d1e098328ec5b0d567335c5982b0622ccce
 SHA512:
-  metadata.gz: a6b83acddf5fc81320a9cb370e2212b5ae173c2a73e838247082ac97222cf404b56a446f37819d9b681f0c4ba1a05280d81dd1e164a0a35d650fd9f0dd1f9ed3
-  data.tar.gz: '0013798bab6a0a057b10a9100fb751cbf85589a31502284b79e1612141b341494bd5e12b6a978b56be3ba6f2842ecf06b203abc033965ed32d62581575858dbe'
+  metadata.gz: 9fe5fea5c0e07c85cbac8ca55ec947ce59d1a999ec9cfc99d3cd1beeb0615ced473e41ae89f2a2561f7edfeb20c24102a751ffe4eb4b84111df3abff8ca234fd
+  data.tar.gz: bb3d6b92463ba8c4833400c35b99f1de62fc0304e31203b2d34e8f6e3ef3aef81aba2c4c83886cf296db76f3526d473ca2cea1a01c53ccfce56613d454746a94

data/config/locales/en.yml

@@ -0,0 +1,55 @@
+# Every message a guard or a command can put in front of a person (§7, §5.9).
+#
+# `reason` is the contract - controllers branch on the symbol, views render it as a disabled
+# button's tooltip - and these strings are what the tooltip says. They are written for the person
+# being refused, not for the developer reading a log: none of them names a configuration key.
+#
+# Nothing here is required. `ChangeRequests::Translation` passes a usable default to every lookup,
+# so the domain core keeps working with no locale file loaded at all - which is exactly what the
+# headless spec asserts, where the message *is* the reason symbol.
+en:
+  change_requests:
+    errors:
+      # One key per entry of Guards::Base::REASONS.
+      already_decided: "You have already decided this step."
+      already_finalized: "This request is already finished."
+      attempts_exhausted: "This request has used all of its attempts."
+      body_required: "A comment needs something in it."
+      executing: "This request is running right now."
+      may_not_request: "Your kind of account cannot raise change requests."
+      not_approved: "This request has not been approved yet."
+      not_expirable: "Only a pending or approved request can expire."
+      not_expired: "This request has not reached its expiry date."
+      not_pending: "This request is no longer open for decisions."
+      not_permitted: "You are not one of this request's approvers."
+      not_system: "Expiry is the clock's to decide, not yours."
+      not_the_approver: "You can only take back your own decision."
+      operation_undeclared: "This request's operation no longer exists, so it can never run."
+      reason_required: "A reason is required."
+      requester: "You cannot decide on your own request."
+      stage_not_current: "This step is not the one waiting on you."
+      stage_not_open: "This step is closed."
+
+      # One key per error class that carries a reason, used when a caller raises without one -
+      # Refusal#i18n_key falls back to the class name underscored.
+      not_approvable: "This request cannot be approved."
+      not_authorized: "You are not allowed to do that."
+      not_cancelable: "This request cannot be cancelled."
+      not_executable: "This request cannot be executed."
+      not_rejectable: "This request cannot be rejected."
+      not_unapprovable: "This decision cannot be taken back."
+      override_not_permitted: "You are not allowed to override the approvals."
+      quorum_not_met: "This request does not have the approvals it needs."
+      transition_error: "This request will not accept that."
+
+    # Stage and quorum names are declaration identifiers, not display text (§5.9). A host adds a key
+    # per name it declares; anything unlisted falls back to `name.humanize`, so "sign_off" reads as
+    # "Sign off" with no locale entry at all.
+    #
+    #   stages:
+    #     sign_off: "Director sign-off"
+    #   quorums:
+    #     owners: "Owners"
+    stages:
+      # The only name the gem itself creates - `op.approvals` builds one stage called this.
+      approval: "Approval"

data/docs/adr/0011-system-sentinel-actor.md

@@ -6,7 +6,9 @@
 ## Context
 
 Some transitions have no human behind them: a request expiring, a reaper closing out an
-interrupted execution, a cleanup task cancelling requests whose operation was removed. The audit
+interrupted execution, a cleanup task cancelling requests whose operation was removed, and — the
+most frequent case by far — **every stage closing**, since workflow evaluation is an internal command
+with no actor of its own ([ADR-0017](0017-approvals-count-through-links.md)). The audit
 trail still has to say who did it.
 
 Leaving the actor columns NULL makes every reader handle a null case, and makes "nobody" and "we

data/docs/adr/0012-declared-error-taxonomy.md

@@ -17,11 +17,17 @@ controller, with finer branches for the cases they handle specially. That code d
 Everything descends from `ChangeRequests::Error`; refused transitions descend from
 `TransitionError`, execution failures from `ExecutionError`.
 
-`TransitionError` carries `#request` and `#reason`. **`reason` is the contract** — controllers branch
+Every refusal carries `#request` and `#reason`. **`reason` is the contract** — controllers branch
 on it and views render it as a disabled button's tooltip — while the message is for humans and is
 translated through the same key the guard uses, so a disabled button and a raised error cannot word
 the same refusal differently.
 
+That pair lives in a `Refusal` **module**, included by `TransitionError` *and* by `NotAuthorized`. A
+shared base class would have made `NotAuthorized` a member of the transition family, and it is
+deliberately a sibling: "the actor may never do this" is a different answer from "not yet", and hosts
+rescue them apart. A guard raises whichever class it declared
+([ADR-0015](0015-one-guard-object-per-transition.md)) and the host branches on `#reason` either way.
+
 Errors raised for unsupported operations rather than refused domain transitions stay in ActiveRecord's
 taxonomy; see [ADR-0007](0007-append-only-audit-trail.md).
 

data/docs/adr/0015-one-guard-object-per-transition.md

@@ -0,0 +1,60 @@
+# ADR-0015: Consult one guard object for every transition
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+Every transition is asked about twice: once by the view, to decide whether the button is enabled,
+and once by the command, to decide whether the write happens. Answering it twice means two
+implementations of the same rule, and the failure mode is a button that offers something the command
+then refuses — with different wording, or no wording at all.
+
+The rules themselves are not one condition but an ordered list of them. "You cannot approve this"
+covers a finished request, a request on another stage, a decision already given, and an actor with
+no standing at all. Which of those a person is told is the whole of the user experience.
+
+## Decision
+
+One guard class per transition, under `lib/change_requests/guards/`, constructed as
+`(request:, actor:, **options)`. It answers `allowed?`, `reason` and `check!`, and both the command
+and the presenter build the same object.
+
+- A subclass implements `refusal`, which returns `nil` to permit or a symbol from
+  `Guards::Base::REASONS`, the closed shared vocabulary. Branch order inside `refusal` is part of
+  the contract: it decides which of several true refusals the person is shown.
+- `refuses_with` declares the error class, rather than deriving it from the guard's name —
+  `Comment` and `Expire` refuse with `NotAuthorized`, the decision guards with their own
+  `TransitionError` ([ADR-0012](0012-declared-error-taxonomy.md)).
+- One reason overrides that declaration: `:already_finalized` always raises `AlreadyFinalized`,
+  whichever guard produced it, so a host rescuing "this request is over" catches every command. It
+  is the same class and the same reason the model's terminal-state guard raises underneath.
+- The undeclared-operation refusal lives in `Guards::Base` and runs before `refusal`, so no guard
+  repeats it. `Comment` opts out with `exempt_from_undeclared_operation!` — a request stranded by a
+  removed declaration is exactly the one someone needs to leave a note on.
+
+**There is no `Guards::Create`.** A guard asks "may this actor do X *to this row*", and at creation
+there is no row. `Commands::Create` runs the three equivalent checks inline. The presenter's half of
+the question — may this actor raise a request at all — is a property of the operation and the actor's
+registered type, and will be answered by `Operation#requestable_by?` reading the same
+implementation, not by a guard carrying a second signature.
+
+## Consequences
+
+### Positive
+
+- A disabled button and a raised error cannot disagree, because they are the same object.
+- `reason` is a symbol, so a host branches on it without parsing English, and the wording is a
+  translation rather than a string in the code ([ADR-0020](0020-refusal-vocabulary-and-fallback.md)).
+- One shape for every guard means one shared example can run against all of them — which is how the
+  undeclared-operation exemption and the cross-guard reason table are asserted at all.
+
+### Negative
+
+- `REASONS` is public API. A symbol cannot be renamed without breaking host code that branches on
+  it, and the vocabulary grows monotonically.
+- Branch order is load-bearing but invisible: nothing in the type system says `:already_finalized`
+  must precede `:not_pending`, only a cross-guard spec that asserts the two answers line up. They
+  had already drifted once before that spec existed.
+- A guard resolves the acting actor through the registry, so an unregistered class raises
+  `UnknownActorType` rather than producing a refusal. The allowlist is deliberately not a reason.

data/docs/adr/0016-commands-are-the-only-writers.md

@@ -0,0 +1,66 @@
+# ADR-0016: Make commands the only writers, under one lock and one event path
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+A request's state lives in several rows: the request, its current stage, its quorums, an approval and
+its quorum links, and an event. A transition touches most of them. If callers assemble those writes
+themselves, every call site is a chance to write four of the five, and the audit trail is the first
+thing to be forgotten because it is the only one nothing else depends on.
+
+Concurrency makes the same point sharper. Two approvals arriving together must not both believe they
+were the last one needed.
+
+## Decision
+
+One command class per transition, under `lib/change_requests/commands/`. `Commands::Base.call`
+resolves the guard, performs the writes and emits the event, and **wraps the whole body in
+`request.with_lock`** — `SELECT … FOR UPDATE`, which also reloads, so a command reads the row it
+locked rather than the object it was handed.
+
+- **Commands raise.** There is no result object and no `success?`. A refusal is an exception carrying
+  a reason ([ADR-0012](0012-declared-error-taxonomy.md)), because the caller that ignores a returned
+  failure is the caller that writes the bug.
+- **Commands never accept permissions from the caller.** They take an actor; the gem resolves that
+  actor's permissions through the registry ([ADR-0018](0018-eligibility-is-data.md)). A
+  caller-supplied permission set is unverifiable by the gem and untestable by the host.
+- **`emit` is the single write path for events.** It stamps the actor triple (or the System
+  sentinel, [ADR-0011](0011-system-sentinel-actor.md)), `occurred_at`, and the `operation_version`
+  read live from the declaration — deliberately not the request's creation-time value, which the row
+  already holds. The rule is enforced by a spec that scans `lib/` and fails if any other file writes
+  an event.
+- **Lost races surface as domain refusals.** `on_conflict` declares which `TransitionError` an
+  `ActiveRecord::RecordNotUnique` becomes, so the loser of a duplicate-decision race is told
+  `:already_decided` rather than getting a 500. An unmapped conflict is re-raised: that is a bug to
+  see, not a refusal to dress it up as.
+- `ActiveRecord::StaleObjectError` maps to `StaleRequest`. `lock_version` is the belt to
+  `with_lock`'s braces.
+
+Two commands depart from the shape, each for a stated reason. `Commands::Create` has no row to lock
+until it has written one, so it wraps a transaction instead — the request and its whole stage,
+quorum, permission and eligible-actor graph are all-or-nothing.
+`Commands::EvaluateWorkflow` ([ADR-0017](0017-approvals-count-through-links.md)) takes no lock of its
+own: it is internal, invoked only from inside a caller that already holds one, and re-locking would
+reload the row that caller has just written to.
+
+## Consequences
+
+### Positive
+
+- Every state change goes through one place per transition, so the event, the status and the rows
+  cannot drift apart.
+- Two command bodies are never inside the same request at once; that is asserted by measuring
+  overlap on real threads rather than by removing the lock and hoping the scheduler cooperates
+  ([ADR-0021](0021-serialise-commands-let-the-index-arbitrate.md)).
+- A host rescues `ChangeRequests::Error` once and gets a flash instead of an exception page.
+
+### Negative
+
+- Every transition holds a row lock for the duration of its writes, including the event insert.
+- The `emit` invariant is enforced by scanning source text. It is stronger than a runtime assertion
+  — it catches a path no spec exercises — but it is a regular expression over the tree, and a
+  sufficiently creative write would slip past it.
+- Commands return the request, except `Comment`, which returns the event it wrote, because the
+  request is unchanged by it.

data/docs/adr/0017-approvals-count-through-links.md

@@ -0,0 +1,77 @@
+# ADR-0017: Count approvals only through the links written at decision time
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+"Is this stage satisfied?" can be answered two ways. Either re-evaluate every approver against every
+quorum whenever something changes, or record at decision time which quorums an approval counted
+toward and count those rows afterwards.
+
+Re-derivation has a failure mode that is easy to miss and impossible to explain afterwards: an
+approver's permissions change, the re-evaluation no longer matches them to the quorum they approved,
+and a request that was approved quietly is not any more. Nobody did anything, and the audit trail
+shows nothing, because nothing happened.
+
+## Decision
+
+`change_request_approval_quorums` records which quorums an approval counted toward, written by the
+command at decision time and **never re-derived**
+([ADR-0007](0007-append-only-audit-trail.md) makes the rows immutable). A quorum is satisfied when
+its linked approvals reach its `threshold`, and that count is the only rule.
+
+`ChangeRequests::Commands::EvaluateWorkflow` is the only code that changes stage or request status as
+a consequence of a decision. It is a command like any other
+([ADR-0016](0016-commands-are-the-only-writers.md)) but internal: no actor, never called by a host,
+invoked only from `Approve`, `Unapprove` and `Reject` inside the lock they already hold. It runs in
+order:
+
+0. A rejection standing on the current stage makes it `rejected`, whatever its approvals say; a stage
+   that was rejected and holds none any more returns to `pending`, with its approvals still counting.
+1. Recount every quorum of the current stage from its links, setting or clearing `satisfied_at`.
+2. The stage is satisfied when **any** of its quorums is, or **all**, per `satisfied_by`.
+3. A satisfied stage closes immediately, and the request advances to the next stage — or becomes
+   `approved` when none remains.
+
+Closing emits one `quorum_satisfied` per satisfied quorum and then one `stage_satisfied`, both
+attributed to the System sentinel ([ADR-0011](0011-system-sentinel-actor.md)). Closing a stage is the
+gem's own act, not the approver's: the approvals that caused it are already in the trail one row
+earlier, each naming the person who gave it, and attributing the close to whoever approved last would
+assert a decision that person never made.
+
+**Closed stages are immutable and there is no rollback into an earlier one.** A stage's outcome, once
+closed, is a historical fact. Rejection is a stop rather than a count: one rejection from an eligible
+approver or from the requester stops the stage, and no rejection threshold is modelled.
+
+## Consequences
+
+### Positive
+
+- A later role change cannot silently un-approve a request. The links say what was true when the
+  decision was made, which is the only moment at which it was a decision.
+- Counting is a `GROUP BY` over an indexed table rather than a re-evaluation of every approver
+  against every quorum.
+- Step 0 is correct at every cooldown value, so the window that a later milestone puts between
+  stopping a stage and finalising the request extends this command instead of rewriting it.
+
+### Negative
+
+- **The `all_quorums` linking rule is not implemented yet.** Under `any_quorum` an approval links to
+  every quorum the actor qualifies for, which is right, because satisfying any one of them ends the
+  stage. Under `all_quorums` it should link to exactly one — the lowest-`position` quorum the actor
+  qualifies for — so that one person holding two roles cannot close two quorums that must both be
+  met. It currently links to all of them, so an actor holding both `admin` and `owner` satisfies
+  "one Admin **and** one Owner" alone. The stage-satisfaction half of `all_quorums` ships and is
+  correct; only the linking half is outstanding. No shipped declaration syntax can build such a
+  stage — `op.approvals` describes one stage holding one quorum — so nothing reaches it today, and
+  it must be closed before the workflow DSL makes multi-quorum stages declarable.
+- **`quorum_satisfied` is emitted when the stage closes, not when the quorum was met.** For a
+  single-quorum stage the two moments are the same. Under `all_quorums` they are not: a quorum met by
+  an earlier approval gets its event later, timestamped at the close, and a quorum on a stage that
+  never closes gets none at all. The trail never claims a satisfaction that was later withdrawn,
+  which is the compensation, but it does not yet answer "when was this counting rule met".
+- Reopening a rejected stage does not clear `rejected_at`. Nothing writes that column yet, so there
+  is nothing stale to clear; the milestone that starts writing it has to clear it here.
+- `Stage`'s `satisfied` status and `satisfied_at` are unreachable while every cooldown is zero: a
+  satisfied stage closes in the same breath. They exist for the window that has not shipped.

data/docs/adr/0018-eligibility-is-data.md

@@ -0,0 +1,64 @@
+# ADR-0018: Express eligibility as data, with one implementation of the predicate
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+"Who may approve this?" has to be answered in three places that must never disagree: the guard, for
+one loaded request; the inbox query, for every request awaiting a given actor; and the host's own
+policy, where it has one. Expressing eligibility as a block or a lambda answers the first and makes
+the second impossible — a predicate in Ruby cannot be paginated.
+
+Hosts also differ in shape. Some have one `User` class and roles; some have `User`, `Admin` and
+`Manager` with different key types and unrelated permission models. A gem that assumes either one is
+useless to the other.
+
+## Decision
+
+Eligibility is rows, not code. A quorum carries **permission rows** (`permission` × `actor_type`,
+each independently nullable) and **named-actor rows**, and the two are OR-ed
+([ADR-0008](0008-staged-multi-quorum-schema.md)).
+
+| `actor_type` | `permission` | Means                                   |
+|--------------|--------------|-----------------------------------------|
+| `User`       | `editor`     | Users holding `editor`                  |
+| `NULL`       | `editor`     | anyone holding `editor`                 |
+| `Admin`      | `NULL`       | any Admin, whatever their permissions   |
+| `NULL`       | `NULL`       | rejected — constraining nothing is a bug |
+
+`permission_match` sits on the **quorum**, not in global configuration: the same rows mean "any of
+these" under `any` and "this actor holds every one of them" under `all`. Identical data, opposite
+meanings, so the mode belongs beside the rows it governs. Configuration supplies only the default.
+
+An actor's permissions are read through **their registered type's lambda**, never through a method on
+the actor, so `User` and `Admin` may derive them completely differently and still be compared against
+one quorum definition.
+
+`Authorization::Permissions#allows?(actor:, quorum:)` is the one implementation of the predicate, and
+`Guards::Base#qualifying` is its one caller. A host replaces it wholesale by assigning
+`config.authorization`; a bare `->(actor:, request:, stage:, action:)` is coerced into
+`Authorization::Callable` on assignment, so the host writes a lambda and the gem still has an object
+answering `allows?`.
+
+## Consequences
+
+### Positive
+
+- The inbox becomes one indexed, paginated query over the same rows the guard reads, rather than a
+  scan through Ruby.
+- Heterogeneous actor classes are a first-class case, not a workaround
+  ([ADR-0003](0003-actor-references-as-triples.md)).
+- Because the rows are materialised per request and immutable, editing an operation's permission
+  list never changes who may approve something already in flight.
+
+### Negative
+
+- Four joins to answer "may this person approve?", where a lambda would have been one call.
+- A quorum with no permission rows grants eligibility to nobody by permission — "all of nothing" has
+  to be special-cased, or a named-approver quorum would admit everyone under `permission_match: all`.
+- When the inbox query ships, its SQL and this Ruby predicate become two expressions of one rule. The
+  mitigation is that there is exactly one Ruby implementation and one shared table of cases for the
+  SQL to be held against, not that the risk is absent.
+- An unregistered actor class raises rather than returning false. That is the allowlist working, but
+  it means the predicate is not total over arbitrary objects.

data/docs/adr/0019-separation-of-duties.md

@@ -0,0 +1,61 @@
+# ADR-0019: Refuse the requester by identity, and make only execution configurable
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+The point of an approval workflow is that somebody other than the requester agrees. A setting that
+turns that off — `requester_may_approve` — is an argument waiting to happen: it implies the gem has
+an opinion that could reasonably be overridden, and it would be set to `true` in exactly the
+installations where four eyes mattered most.
+
+Execution is a different question. Running an approved change is not a second opinion, and plenty of
+sound processes have the person who asked for it press the button once others have agreed.
+
+Both questions are the same underlying one — is this the same human twice — and that question is not
+answerable from `(type, id)` alone when a host has several actor classes backed by one person.
+
+## Decision
+
+**The requester can never approve their own request**, and there is no setting to the contrary: no
+reader, no writer, no constant. `Guards::Approve` compares identity and consults nothing. Naming the
+setting, even to hard-code it to `false`, would imply it were negotiable.
+
+**Execution is configurable**, in three independent places:
+
+- `t.may_execute` on the registered actor type — whether this *class* of actor may execute at all,
+  checked before the separation-of-duties branches so a class declared unable to execute never passes
+  a guard a presenter consults.
+- `config.requester_may_execute`, default `false`.
+- `config.approver_may_execute`, default `true`. "An approver" means someone who wrote a row in
+  `change_request_approvals` — who actually spent a decision — not merely someone eligible to.
+
+**`config.actor_identity` is the opt-in answer to "the same human twice".** When a host supplies it,
+it stands in for `(type, id)` in three places: refusing the requester as an approver, refusing a
+second decision on one stage, and `Execute`'s separation-of-duties branches. All three go through one
+helper, `Guards::Base#same_person?`, so they cannot answer differently.
+
+It is deliberately **not** consulted by `Unapprove`. Identity decides who counts as one person when
+tallying decisions; retracting is about which row this actor wrote, and letting one actor delete
+another's row would make the trail say something untrue.
+
+## Consequences
+
+### Positive
+
+- The gem's central promise is not a configuration value, so it cannot be turned off by an
+  initializer nobody reviewed.
+- Hosts with several actor classes over one identity get the cross-class rules by supplying one
+  lambda, and hosts without one lose nothing they had.
+- Separation of duties for execution is expressible without weakening approval.
+
+### Negative
+
+- The database's unique index on `(stage, approver_type, approver_id)` cannot express identity, so
+  under `config.actor_identity` the guard is deliberately stricter than the constraint behind it. A
+  caller bypassing the guard could still write the second row.
+- Three settings govern execution and their interaction is only legible by reading the guard's branch
+  order.
+- A host that genuinely wants self-approval — a single-operator installation, say — has no route to
+  it and must not use the gem for that workflow.

data/docs/adr/0020-refusal-vocabulary-and-fallback.md

@@ -0,0 +1,54 @@
+# ADR-0020: Ship refusal reasons as a closed vocabulary that degrades to the symbol
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+A refusal has two audiences. Host code needs something stable to branch on; a person needs a
+sentence. Returning a string serves the second badly and the first not at all, and translating in the
+guard puts wording in the domain core — which must keep working in a process where `I18n` was never
+configured ([ADR-0001](0001-headless-domain-core.md)).
+
+## Decision
+
+`Guards::Base::REASONS` is the closed vocabulary of refusal symbols, and the symbol is the contract.
+Wording lives in `config/locales/en.yml` and nowhere else.
+
+- `Refusal#i18n_key` is `change_requests.errors.<reason>`, falling back to the error class name
+  underscored when a caller raised without a reason — so `NotApprovable` has a sentence too.
+- `ChangeRequests::Translation` is the single lookup path. It checks `defined?(I18n)` and every
+  caller passes a usable default, so **with no locale file loaded at all the message is the reason
+  symbol**. That is asserted in the headless subprocess, where the message for `:requester` is
+  literally `"requester"`.
+- The engine needs no code for this: `Rails::Engine` already puts `config/locales` on
+  `I18n.load_path`. Creating the directory is the whole of the wiring.
+- Stage and quorum **names** are declaration identifiers in `snake_case`, not display text. They
+  resolve through `change_requests.stages.<name>` / `change_requests.quorums.<name>` with
+  `name.humanize` as the fallback, so a host that declares `sign_off` reads "Sign off" with no locale
+  entry at all.
+
+A spec holds the vocabulary and the locale file to each other **in both directions**: every reason
+must have a translation, and every translation must correspond to a reason or to an error class that
+can be raised without one. A vocabulary that only ever grows accumulates symbols nothing raises, and
+a translation for a symbol nothing raises is a promise about behaviour the gem does not have.
+
+## Consequences
+
+### Positive
+
+- Hosts branch on symbols and translate independently; overriding one sentence is a locale entry, not
+  a monkey patch.
+- The domain core never depends on a locale file existing, so nothing about i18n reaches back into
+  the headless guarantee.
+- A new reason cannot ship untranslated, and a dead one cannot linger, because the spec fails either
+  way.
+
+### Negative
+
+- The reason symbols are public API and have to be versioned as carefully as the class names
+  ([ADR-0012](0012-declared-error-taxonomy.md)).
+- The bidirectional spec makes adding a reason a two-file change, deliberately.
+- `I18n.load_path` is process-wide, so assertions about the bare-symbol fallback have to use reasons
+  nothing will ever translate; written against real reasons they pass or fail depending on whether
+  some other spec file booted Rails first.

data/docs/adr/0021-serialise-commands-let-the-index-arbitrate.md

@@ -0,0 +1,56 @@
+# ADR-0021: Serialise commands with a row lock and let the unique index arbitrate
+
+- **Status:** Accepted
+- **Date:** 2026-09-12
+
+## Context
+
+Approvals arrive from people, which means they arrive at the same moment often enough to matter. Two
+races are real in an approval workflow and neither is exotic: two approvers racing the last slot of a
+quorum, and one approver double-clicking.
+
+The first must transition the stage exactly once. The second must be refused the way the guard would
+have refused it — a duplicate submission is a user error, and answering it with an exception page
+turns a mis-click into an incident.
+
+## Decision
+
+Every command body runs inside `request.with_lock`
+([ADR-0016](0016-commands-are-the-only-writers.md)), so no two transitions on one request are ever in
+flight together. The lock is taken on the request rather than on the stage: a transition reads the
+stage, its quorums and their links, and decides the request's own status from them.
+
+**The lock is not the guarantee, the unique index is.** `(change_request_stage_id, approver_type,
+approver_id)` is what makes one decision per person per stage true even against a caller that never
+took a lock. The lock narrows the window; the constraint closes it. `on_conflict` is what turns the
+database's answer back into the gem's, so the loser hears `NotApprovable(:already_decided)`.
+
+The regression specs run real threads on real connections against real PostgreSQL, outside the
+suite's transaction — a second connection cannot see uncommitted rows, so these examples truncate
+instead.
+
+**The specs measure serialisation rather than removing the lock.** "Assert the race breaks without
+`with_lock`" is only probabilistically true: the damaging interleaving is likely, not certain, so such
+a spec passes by luck and reddens CI at random. Instead both probes measure the thing the lock exists
+to control — were two command bodies ever inside at the same time? With the lock, never; with it
+removed and the body held open, always. Both directions are deterministic. What the overlap then
+*costs* is deliberately not asserted, because that does depend on the scheduler.
+
+## Consequences
+
+### Positive
+
+- Exactly one of two racing approvals closes the stage, and the stage-closing events are written
+  once rather than once per thread.
+- A lost race is a domain refusal with a reason, never a `RecordNotUnique` reaching the host.
+- The teeth of the concurrency specs are a measurement that holds under any scheduler, so they can
+  run in CI on every commit.
+
+### Negative
+
+- A row lock per transition is a serialisation point on the busiest request, and the lock is held
+  across the event insert.
+- The concurrency examples cannot use rspec-mocks, which is not thread-safe; the probes are ordinary
+  subclasses of the command, which is more code and must be kept in step with it.
+- These examples opt out of transactional fixtures and clean up by truncation, so they are the one
+  group in the suite whose isolation is different from every other.

data/docs/adr/README.md

@@ -5,7 +5,10 @@ One record per significant architectural choice: its context, the decision, and
 These describe the gem **as it stands today**. Decisions still ahead of the implementation live in
 `PLAN.md` until the code that makes them real exists.
 
-A record is never edited once accepted. It is superseded by a later one, which links back to it.
+A record is never rewritten once accepted: a decision that is reversed is **superseded** by a later
+record, which links back to it. A record may still be **corrected** where it describes the code
+inaccurately — these describe the gem as it stands, and a wrong statement left in place is worse
+than an edit.
 
 | ADR | Title | Status |
 |-----|-------|--------|
@@ -23,3 +26,10 @@ A record is never edited once accepted. It is superseded by a later one, which l
 | [0012](0012-declared-error-taxonomy.md) | Declare the whole error taxonomy before raising any of it | Accepted |
 | [0013](0013-json-runtime-pin.md) | Pin `json` to `~> 2.7` as a runtime dependency | Accepted |
 | [0014](0014-executable-architecture-rules.md) | Enforce the architectural boundaries executably | Accepted |
+| [0015](0015-one-guard-object-per-transition.md) | Consult one guard object for every transition | Accepted |
+| [0016](0016-commands-are-the-only-writers.md) | Make commands the only writers, under one lock and one event path | Accepted |
+| [0017](0017-approvals-count-through-links.md) | Count approvals only through the links written at decision time | Accepted |
+| [0018](0018-eligibility-is-data.md) | Express eligibility as data, with one implementation of the predicate | Accepted |
+| [0019](0019-separation-of-duties.md) | Refuse the requester by identity, and make only execution configurable | Accepted |
+| [0020](0020-refusal-vocabulary-and-fallback.md) | Ship refusal reasons as a closed vocabulary that degrades to the symbol | Accepted |
+| [0021](0021-serialise-commands-let-the-index-arbitrate.md) | Serialise commands with a row lock and let the unique index arbitrate | Accepted |

data/lib/change_requests/commands/approve.rb

@@ -23,8 +23,8 @@ module ChangeRequests
         approval = record_decision
         link(approval, guard.countable_quorums)
         emit(:approved, body: comment, metadata: metadata_for(approval))
+        EvaluateWorkflow.call(request: request)
 
-        # Commands::EvaluateWorkflow is M1b-12. Until it lands nothing advances the stage.
         request
       end
 

data/lib/change_requests/commands/create.rb

@@ -93,9 +93,9 @@ module ChangeRequests
         # Unregistered classes are the allowlist's business, and actor_attributes raises for them.
         return if type.nil? || type.may_request
 
-        fail NotAuthorized,
-             "#{requester.class.name} may not raise change requests. " \
-             "Set `t.may_request = true` on its registration (§9.1)."
+        # No message: the reason carries it, so the text comes from the host's locale file and says
+        # nothing about `t.may_request` - a configuration key has no business in a flash (Q45).
+        fail NotAuthorized.new(reason: :may_not_request)
       end
 
       def write_request(declaration)

data/lib/change_requests/commands/evaluate_workflow.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  module Commands
+    # The only code that changes stage or request status as a consequence of a decision (§7.1).
+    #
+    # A command like the others - guard, mutate, emit - but an **internal** one: it takes no actor,
+    # hosts never call it, and it is invoked only from `Approve`, `Unapprove` and `Reject`, inside
+    # the lock they already hold.
+    #
+    # Its events carry the System sentinel, and that is deliberate: closing a stage is the gem's own
+    # act, not the approver's. The approvals that caused it are already in the trail, each with its
+    # own actor, so "System closed the stage" sits directly beneath the rows naming everyone who
+    # approved (§19.15, Q36).
+    class EvaluateWorkflow < Base
+      def self.call(request:)
+        new(request: request).call
+      end
+
+      def perform
+        return request if stage.nil?
+        return request if settle_rejection == :stopped
+
+        satisfy_quorums
+        close_stage! if satisfied?
+
+        request
+      end
+
+      private
+
+      # No lock of its own. The caller holds one, and re-locking would reload the request they just
+      # wrote to - `with_lock` reloads under SELECT … FOR UPDATE. The error mapping in
+      # Commands::Base#call still applies.
+      def around_perform
+        yield
+      end
+
+      def stage
+        @stage ||= request.current_stage
+      end
+
+      # Step 0, before any recount: a rejection outranks any number of approvals. A stage holding one
+      # is `rejected` and cannot be satisfied; a stage that was rejected and holds none any more goes
+      # back to `pending`, and the approvals it already collected are still there to count (§7.1).
+      #
+      # At cooldown 0 - all of M1 - `Commands::Reject` writes the stage and the request rejection in
+      # one lock, so a `pending` request on a rejected stage never exists through the public API.
+      # M9b's window is what makes this reachable; it is correct and cheap at every cooldown value,
+      # so it ships here rather than being bolted on later (Q35).
+      def settle_rejection
+        if stopping_rejection?
+          # M9b owns rejected_at, together with CloseStageJob and the window it measures.
+          stage.update!(status: "rejected") unless stage.rejected?
+
+          return :stopped
+        end
+
+        stage.update!(status: "pending") if stage.rejected?
+
+        :unchanged
+      end
+
+      # Under only_record_rejections a rejection stops nothing: the decision and the event are
+      # recorded, the stage stays open, and everyone else's approvals still count (§7.1). Asking the
+      # config here rather than skipping step 0 outright means a stage rejected before the flag was
+      # turned on still reopens.
+      def stopping_rejection?
+        return false if config.only_record_rejections
+
+        stage.approvals.exists?(decision: "rejected")
+      end
+
+      # Counting is only via change_request_approval_quorums, written at decision time and never
+      # re-derived: a later role change must not silently un-approve a request (§5.3).
+      def satisfy_quorums
+        stage.quorums.each do |quorum|
+          met = quorum.approval_quorums.count >= quorum.threshold
+
+          next if met == quorum.satisfied?
+
+          quorum.update!(status: met ? "satisfied" : "pending", satisfied_at: met ? Time.current : nil)
+        end
+      end
+
+      # any_quorum: at least one. all_quorums: every one - the difference between "one Admin OR two
+      # Owners" and "one Admin AND two Owners" (§5.3). M9a adds the *linking* rule that stops one
+      # person closing two quorums of an all_quorums stage; this is only the counting rule.
+      def satisfied?
+        quorums = stage.quorums.reload
+
+        return false if quorums.empty?
+
+        stage.all_quorums? ? quorums.all?(&:satisfied?) : quorums.any?(&:satisfied?)
+      end
+
+      # §7.1's four writes. Cooldown is M9b, so the window is always zero here and a satisfied stage
+      # closes in the same breath.
+      def close_stage!
+        stage.quorums.select(&:satisfied?).each do |quorum|
+          emit(:quorum_satisfied, metadata: quorum_metadata(quorum))
+        end
+
+        stage.update!(status: "closed", closed_at: Time.current)
+        emit(:stage_satisfied, metadata: quorum_metadata(closing_quorum))
+
+        advance
+      end
+
+      # The quorum that closed it (§7.1). With one nameless quorum per stage there is no name to
+      # give, so the key is omitted rather than emitted as null, as Commands::Approve does (§5.9).
+      def quorum_metadata(quorum)
+        metadata = { stage: stage.name }
+        metadata[:quorum] = quorum.name if quorum&.name.present?
+
+        metadata
+      end
+
+      def closing_quorum
+        stage.quorums.select(&:satisfied?).min_by(&:position)
+      end
+
+      # The sequential advance ships now (D5): deferring it would mean rewriting this command in
+      # M9a rather than extending it.
+      def advance
+        following = request.stages.find_by(position: stage.position + 1)
+
+        return request.update!(status: "approved") if following.nil?
+
+        request.update!(current_stage_position: following.position)
+      end
+    end
+  end
+end

data/lib/change_requests/commands/reject.rb

@@ -26,9 +26,15 @@ module ChangeRequests
         record_decision
         emit(:rejected, body: reason, metadata: metadata)
 
-        stop unless config.only_record_rejections
+        if config.only_record_rejections
+          # The workflow continues, so the stage may still be satisfied by everyone else (§7.1).
+          EvaluateWorkflow.call(request: request)
+        else
+          # No evaluation after `stop`: the request is already `rejected` and final, and re-entering
+          # evaluation on it is at best a wasted query.
+          stop
+        end
 
-        # Commands::EvaluateWorkflow is M1b-12, and only the recorded-only branch would call it.
         request
       end
 

data/lib/change_requests/commands/unapprove.rb

@@ -27,8 +27,10 @@ module ChangeRequests
         decision.destroy!
 
         emit(:unapproved, metadata: metadata)
+        # A quorum that lost its threshold goes back to pending, and a stage whose last rejection
+        # this was reopens (§7.1).
+        EvaluateWorkflow.call(request: request)
 
-        # Commands::EvaluateWorkflow is M1b-12. Until it lands nothing re-counts the stage.
         request
       end
 

data/lib/change_requests/guards/approve.rb

@@ -10,6 +10,10 @@ module ChangeRequests
       refuses_with NotApprovable
 
       def refusal
+        # A finished request is the same refusal whichever command met it, and Q29 maps this one
+        # reason to AlreadyFinalized for every guard. `:not_pending` then means what it says:
+        # open, but not open for decisions (Q48).
+        return :already_finalized if request.final?
         return :not_pending unless request.pending?
         # Never configurable. There is no config.requester_may_approve to read, in any form (I5).
         return :requester if same_person?(request.requester, actor)

data/lib/change_requests/guards/reject.rb

@@ -14,6 +14,10 @@ module ChangeRequests
       refuses_with NotRejectable
 
       def refusal
+        # A finished request is the same refusal whichever command met it, and Q29 maps this one
+        # reason to AlreadyFinalized for every guard. `:not_pending` then means what it says:
+        # open, but not open for decisions (Q48).
+        return :already_finalized if request.final?
         return :not_pending unless request.pending?
         return :stage_not_current if !permitted_here? && eligible_on_another_stage?
         return :already_decided if already_decided?

data/lib/change_requests/guards/unapprove.rb

@@ -10,6 +10,10 @@ module ChangeRequests
       refuses_with NotUnapprovable
 
       def refusal
+        # A finished request is the same refusal whichever command met it, and Q29 maps this one
+        # reason to AlreadyFinalized for every guard. `:not_pending` then means what it says:
+        # open, but not open for decisions (Q48).
+        return :already_finalized if request.final?
         return :not_pending unless request.pending?
         return :not_the_approver if decision.nil?
         return :stage_not_open unless decision.stage.pending?

data/lib/change_requests/models/concerns/string_enum.rb

@@ -8,8 +8,9 @@ module ChangeRequests
     #   string_enum :status, %w(pending satisfied closed)
     #   Stage.statuses #=> [...]   Stage.pending #=> scope   stage.pending? #=> true
     #
-    # Not Rails' enum: it owns the reader and writer, maps through a hash, and raises at assignment
-    # instead of reporting a validation error.
+    # Not Rails' enum: no generated writer, no mapping hash, no dangerous-name collision check, and
+    # no class-level constant. An out-of-range value is assigned as given and reported by the
+    # inclusion validation; the CHECK constraint is the floor beneath that.
     module StringEnum
       extend ActiveSupport::Concern
 

data/lib/change_requests/models/event.rb

@@ -12,13 +12,15 @@ module ChangeRequests
 
     KINDS = %w(
       requested approved unapproved rejected commented canceled
-      quorum_satisfied stage_satisfied stage_closed overridden
+      quorum_satisfied stage_satisfied overridden
       execution_started executed execution_failed
       expired reaped operation_undeclared
     ).freeze
 
     # Inclusion only, no CHECK: every later milestone adds kinds, and a CHECK would make each one a
-    # migration in every host application (§19.16).
+    # migration in every host application (§19.16) - which is also why `stage_closed` could simply be
+    # dropped when it turned out nothing emitted it. Cooldown (M9b) puts a window between
+    # satisfaction and closing, and brings it back if it needs one (Q41).
     string_enum :kind, KINDS
 
     belongs_to :change_request, class_name: "ChangeRequests::Request", inverse_of: :events

data/lib/change_requests/models/quorum_permission.rb

@@ -3,8 +3,8 @@
 module ChangeRequests
   # Eligibility by permission × actor type, both independently nullable (§5.3):
   #
-  #   ("User", "editor")  Users holding :editor      (NULL, "editor")  anyone holding :editor
-  #   ("Admin", NULL)     any Admin                  (NULL, NULL)      rejected
+  #   ("editor", "User")  Users holding :editor      ("editor", NULL)  anyone holding :editor
+  #   (NULL, "Admin")     any Admin                  (NULL, NULL)      rejected
   #
   # Write-once: materialised from the frozen workflow when the request is created, so editing an
   # operation's permission list never changes who may approve a request already in flight.

data/lib/change_requests/testing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ChangeRequests
+  # The minimum needed to write a concurrency spec (§15.3). The host-facing test kit is M8.
+  module Testing
+    module_function
+
+    # Runs the block on `count` real threads, each with its own connection, released together.
+    #
+    #   results = Testing.in_parallel(2) { |i| Commands::Approve.call(request:, actor: actors[i]) }
+    #
+    # Returns one entry per thread, in order: the block's value, or the exception it raised.
+    # Raising is an outcome here rather than a failure - "the loser of this race is told X" is the
+    # whole claim - so nothing is re-raised and the caller decides what the pair should be.
+    #
+    # Threads start blocked on a barrier and are released at once, which is what makes them race
+    # rather than run one after another. `connection_pool.with_connection` gives each its own
+    # connection and returns it afterwards, so the pool is not drained by a spec that fails.
+    def in_parallel(count)
+      gate = Barrier.new(count)
+
+      threads = Array.new(count) do |index|
+        Thread.new do
+          ActiveRecord::Base.connection_pool.with_connection do
+            gate.wait
+            begin
+              yield(index)
+            rescue StandardError => e
+              e
+            end
+          end
+        end
+      end
+
+      threads.map(&:value)
+    end
+
+    # Everyone waits until the last one arrives, then all proceed. Ruby ships no barrier and
+    # concurrent-ruby is not a dependency of this gem.
+    class Barrier
+      def initialize(count)
+        @count = count
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @arrived = 0
+      end
+
+      def wait
+        @mutex.synchronize do
+          @arrived += 1
+
+          next @condition.broadcast if @arrived >= @count
+
+          @condition.wait(@mutex) while @arrived < @count
+        end
+      end
+    end
+  end
+end

data/lib/change_requests/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChangeRequests
-  VERSION = "0.2.2"
+  VERSION = "0.2.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: change_requests
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.5
 platform: ruby
 authors:
 - Andreas Finger
@@ -308,6 +308,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- config/locales/en.yml
 - config/routes.rb
 - docs/08_events_and_notifications.md
 - docs/adr/0001-headless-domain-core.md
@@ -324,6 +325,13 @@ files:
 - docs/adr/0012-declared-error-taxonomy.md
 - docs/adr/0013-json-runtime-pin.md
 - docs/adr/0014-executable-architecture-rules.md
+- docs/adr/0015-one-guard-object-per-transition.md
+- docs/adr/0016-commands-are-the-only-writers.md
+- docs/adr/0017-approvals-count-through-links.md
+- docs/adr/0018-eligibility-is-data.md
+- docs/adr/0019-separation-of-duties.md
+- docs/adr/0020-refusal-vocabulary-and-fallback.md
+- docs/adr/0021-serialise-commands-let-the-index-arbitrate.md
 - docs/adr/README.md
 - lib/change_requests.rb
 - lib/change_requests/authorization/callable.rb
@@ -333,6 +341,7 @@ files:
 - lib/change_requests/commands/cancel.rb
 - lib/change_requests/commands/comment.rb
 - lib/change_requests/commands/create.rb
+- lib/change_requests/commands/evaluate_workflow.rb
 - lib/change_requests/commands/expire.rb
 - lib/change_requests/commands/reject.rb
 - lib/change_requests/commands/unapprove.rb
@@ -370,6 +379,7 @@ files:
 - lib/change_requests/operation.rb
 - lib/change_requests/operations.rb
 - lib/change_requests/presenters/.keep
+- lib/change_requests/testing.rb
 - lib/change_requests/translation.rb
 - lib/change_requests/version.rb
 - lib/change_requests/workflow.rb