change_requests 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04c87793dcb0c59f3124d3924f6599486406f3df811c5f61fc1be2840b015c0c
-  data.tar.gz: fd410e8de4959c5f1155ec334fc09731370040582c56a6d2b1b9f387f08828cf
+  metadata.gz: 205a020929c71027848bc891897a26676a96fbc2c77a6d2e32aa5cedc577109c
+  data.tar.gz: 172b2e90ff436bd10e42e5a30eb18052b65b20bf660156efec238b58aa58abf5
 SHA512:
-  metadata.gz: bc2b298c8470e7f4389361a50870d146f6f7181a160e710148e4b26ffed3f55cfa3b6d0f184259760f06bf13aca98fd2e4bf068846261a0d900595db42e514eb
-  data.tar.gz: a3fc1ab98a25f1a88c5f7da19139dcbd2d48b889fc5fdfcbf4d8a974c2b213c2401cbd74fa3638fcdf7257f02ef7049c6a08c7aaa08144470f68159f0198fe14
+  metadata.gz: a6b83acddf5fc81320a9cb370e2212b5ae173c2a73e838247082ac97222cf404b56a446f37819d9b681f0c4ba1a05280d81dd1e164a0a35d650fd9f0dd1f9ed3
+  data.tar.gz: '0013798bab6a0a057b10a9100fb751cbf85589a31502284b79e1612141b341494bd5e12b6a978b56be3ba6f2842ecf06b203abc033965ed32d62581575858dbe'

data/README.md

@@ -28,6 +28,11 @@ gem install change_requests
 
 TODO: Write usage instructions here
 
+## Architecture
+
+The decisions behind the gem's shape — and what each one costs — are recorded as ADRs in
+[docs/adr/](docs/adr/README.md).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/docs/adr/0001-headless-domain-core.md

@@ -0,0 +1,40 @@
+# ADR-0001: Keep the domain core headless
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+Approval workflows are triggered from more places than a controller: a rake task, a console session,
+a background job, an API client. A gem whose domain logic can only load inside a booted Rails
+application forces every one of those callers through a framework it does not otherwise need, and
+makes the gem's own test suite slower and less honest than it should be.
+
+ActiveRecord is unavoidable — the gem owns nine tables. The rest of Rails is not.
+
+## Decision
+
+Everything under `lib/change_requests/` except `engine.rb` is domain code and loads with `Rails`
+undefined. The entrypoint requires only `active_record` and `zeitwerk`, then calls
+`ChangeRequests.load_engine!`, which returns early unless `::Rails::Engine` is already defined.
+Loading the Rails layer is therefore opt-in and driven by the host's own boot order.
+
+Because `require` fires once, `load_engine!` is public and idempotent: a host that requires this gem
+before Rails exists can call it again afterwards.
+
+## Consequences
+
+### Positive
+
+- The domain runs from any process that can open a database connection.
+- No domain file may name `Rails`, `ActionController`, `ActionView`, `ActionDispatch` or
+  `ActiveJob`; see [ADR-0014](0014-executable-architecture-rules.md) for how that is enforced.
+- The headless path is exercised for real: an integration spec migrates the schema and builds a
+  request graph in a subprocess that never requires Rails.
+
+### Negative
+
+- Conveniences that are free inside Rails — `I18n`, time zones, ActiveJob — must be reached
+  defensively or declared optional. `ChangeRequests::Translation` exists only for that reason.
+- The two Rails-facing references the entrypoint is allowed are `defined?`-guarded and must stay
+  that way, which is easy to regress and needs an explicit rule to prevent.

data/docs/adr/0002-mountable-engine-with-isolated-namespace.md

@@ -0,0 +1,38 @@
+# ADR-0002: Ship the Rails layer as a mountable engine with an isolated namespace
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+The gem ships models, and will ship routes, controllers and views. Dropped into a host application
+unnamespaced, those would collide with the host's own `Request`, `Approval` or `Event`, and the
+gem's routes would appear at paths the host did not choose.
+
+## Decision
+
+`ChangeRequests::Engine` is a mountable `Rails::Engine` calling `isolate_namespace ChangeRequests`.
+It is the only file in the gem that touches Rails, and Zeitwerk ignores it so that an eager load in
+a headless process cannot pull Rails in ([ADR-0001](0001-headless-domain-core.md)).
+
+`ChangeRequests.table_name_prefix` is defined on the module **before** `engine.rb` can load.
+`isolate_namespace` installs its own prefix only `unless mod.respond_to?(:table_name_prefix)`, and
+its version yields `change_requests_stages`; ours yields `change_request_stages`.
+
+The engine validates the host's configuration in `config.after_initialize`, so a misconfiguration
+fails the boot rather than the first request that touches the gem.
+
+## Consequences
+
+### Positive
+
+- No constant, table name or route leaks into the host.
+- Every table name is derived from one prefix plus the model name. Only `Request` sets a table name
+  explicitly, because the convention would give it `change_request_requests`.
+- Configuration errors surface at deploy time, listed all at once.
+
+### Negative
+
+- The prefix must stay defined ahead of the engine. It is load-order-sensitive and silently wrong if
+  reordered, so a spec asserts it against a real engine boot.
+- The host must mount the engine to get any of the Rails-facing features.

data/docs/adr/0003-actor-references-as-triples.md

@@ -0,0 +1,43 @@
+# ADR-0003: Reference host actors by a (type, id, label) triple
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+The gem records who requested, who approved and who executed, but knows nothing about the host's
+user model. Hosts have several actor classes at once (`User`, `Admin`, `Accounts::Manager`), key
+them with integers, uuids or strings, and delete them. A foreign key into a host table would force
+one class, one key type, and would take the audit trail down with the record.
+
+## Decision
+
+Every actor reference is three columns: `*_type`, `*_id` and, where a decision was recorded,
+`*_label`.
+
+- `*_id` is a **string** column, so heterogeneous primary key types share it.
+- `*_type` is validated against `ChangeRequests.config.actor_types`, a registry the host declares.
+  The registry is the allowlist: a stored type string is compared against it and is never
+  `constantize`d to decide whether it is acceptable.
+- `*_label` is **snapshotted at write time** through the lambda the registration supplies, and is
+  never recomputed.
+
+No foreign key in the gem points at a host table, and none ever will.
+
+## Consequences
+
+### Positive
+
+- A request stays readable after the actor record is deleted or renamed.
+- A typo in a type string fails at creation, not at render time.
+- Hosts mix actor classes and key types freely. A registration also declares the class's `key_type`,
+  so a reader can cast the string back to the host's own key.
+
+### Negative
+
+- The stored label is a snapshot and drifts from the record. `config.actor_label_strategy` exists so
+  that readers can prefer the live record and fall back to the snapshot.
+- Nothing at the database level guarantees an actor still exists; referential integrity here is a
+  deliberate non-goal.
+- Every actor class must be registered before it can request or approve, which is one more thing a
+  host has to remember.

data/docs/adr/0004-uuid-primary-keys.md

@@ -0,0 +1,35 @@
+# ADR-0004: Use uuid primary keys for every gem-owned table
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+The gem creates nine tables in the host's database. An earlier draft let the host choose between
+uuid and bigint at install time, via a `--primary-key-type` flag on the install generator. That
+choice doubles the schema surface under test, has to be threaded through every foreign key in the
+migration template, and was never actually asked for.
+
+## Decision
+
+Every gem-owned primary key and every foreign key between gem-owned tables is a `uuid`. There is no
+install-time flag and no bigint variant.
+
+This says nothing about the host's own tables. `config.actor_type … t.key_type` is a different
+setting, describing how a host record's key is cast into the gem's string `*_id` column
+([ADR-0003](0003-actor-references-as-triples.md)).
+
+## Consequences
+
+### Positive
+
+- One schema shape to test, document and migrate.
+- A request id is safe to put in a URL, and is what execution hands to targets declaring a
+  `change_request_id:` keyword, so no separate idempotency key column is needed.
+
+### Negative
+
+- Requires `gen_random_uuid()`. PostgreSQL 13 and later provide it natively; an older host has to
+  enable `pgcrypto` itself, because the migration does not enable extensions in the host's database.
+- Wider indexes, and no natural insertion order — `created_at` is the ordering column everywhere.
+- A host that keys everything else with bigints gets a mixed convention it did not choose.

data/docs/adr/0005-string-states-with-check-constraints.md

@@ -0,0 +1,43 @@
+# ADR-0005: Store states as strings with CHECK constraints, not PostgreSQL enums
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+Seven columns hold a closed set of values: a request's `status`, a stage's `status` and
+`satisfied_by`, a quorum's `status` and `permission_match`, an approval's `decision` and an
+attempt's `outcome`. The obvious database-native answer is a PostgreSQL enum type.
+
+The gem is an engine, so its schema lives in other people's applications. A milestone that adds one
+state to one of those sets would then require an `ALTER TYPE` migration in every host that installed
+the gem.
+
+## Decision
+
+Those columns are `string`, constrained twice:
+
+- a `CHECK` constraint in the migration, so the database refuses an unknown value;
+- a `Concerns::StringEnum` declaration in the model, which adds an inclusion validation, a scope and
+  a predicate per value.
+
+`StringEnum` is not Rails' `enum`: it leaves the column's own reader and writer alone, maps nothing
+through a hash, and reports an unknown value as a validation error rather than raising at
+assignment.
+
+`kind` on the event table is deliberately *not* in this list. It is a validation only, because later
+milestones add kinds and a CHECK would make each one a migration in every host application.
+
+## Consequences
+
+### Positive
+
+- Adding a state is a model change plus one CHECK migration, not a type change coordinated across
+  every installation.
+- Values read as themselves in `psql`, in logs and in the audit trail.
+- The set is enforced at both layers, so a direct `INSERT` cannot write an unknown state.
+
+### Negative
+
+- Wider columns than an enum's four bytes, and the set is declared in two places that must agree.
+- Nothing stops a host from dropping a CHECK constraint and writing whatever it likes.

data/docs/adr/0006-creation-time-immutability.md

@@ -0,0 +1,39 @@
+# ADR-0006: Enforce creation-time immutability in the gem, not with `attr_readonly`
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+Twelve columns on `change_requests` are creation-time facts: what will be invoked, who asked, and
+the labels snapshotted so the row stays readable once the actor and the payload's records are gone.
+Changing any of them after the fact rewrites what a request *was*, which is the one thing an
+approval gate exists to prevent.
+
+Rails' `attr_readonly` **silently discards** the assignment unless the host application has
+`config.active_record.raise_on_assign_to_attr_readonly` enabled — a setting an engine cannot
+control, and silence is exactly the behaviour this column list exists to prevent.
+
+## Decision
+
+`Concerns::ReadonlyAttributes` declares the protected columns with `readonly_after_create` and
+installs a `before_update` guard that raises `ChangeRequests::ReadonlyAttribute`, naming every
+changed attribute at once.
+
+`update_columns` bypasses it, by design: it bypasses callbacks everywhere in Rails, and a method
+whose entire purpose is to skip the model layer should keep doing so.
+
+## Consequences
+
+### Positive
+
+- The refusal is loud and identical in every host, whatever the host's ActiveRecord settings.
+- The error is part of the gem's own taxonomy ([ADR-0012](0012-declared-error-taxonomy.md)), so a
+  host rescues one hierarchy rather than two.
+- It covers `jsonb` columns, which change by mutation as readily as by assignment.
+
+### Negative
+
+- One more `before_update` callback on the hot path of every save.
+- Protection is application-level only. `update_columns`, raw SQL and a console session all go
+  around it; a host wanting more has to add database rules itself.

data/docs/adr/0007-append-only-audit-trail.md

@@ -0,0 +1,42 @@
+# ADR-0007: Make the audit trail and the eligibility rows append-only
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+`change_request_events` is the record of what happened and who did it. Its value depends entirely on
+nobody being able to revise it afterwards.
+
+The eligibility rows — `change_request_quorum_permissions`,
+`change_request_quorum_eligible_actors`, `change_request_approval_quorums` — need the same
+protection for a different reason. They are materialised from the operation's workflow when the
+request is created, and they are the frozen snapshot: editing an operation must never change who may
+approve a request already in flight.
+
+## Decision
+
+`Concerns::Immutable` installs `before_update` and `before_destroy` callbacks that both raise
+`ActiveRecord::ReadOnlyRecord`. It is included by `Event`, `QuorumPermission`,
+`QuorumEligibleActor` and `ApprovalQuorum`.
+
+It raises `ActiveRecord::ReadOnlyRecord`, not a `ChangeRequests::Error`: this is an unsupported
+operation, not a refused domain transition ([ADR-0012](0012-declared-error-taxonomy.md)).
+
+`ON DELETE CASCADE` bypasses it, by design — deleting a request takes its whole graph with it.
+
+## Consequences
+
+### Positive
+
+- History cannot be rewritten through the model layer, including by the gem's own commands.
+- No `dependent:` option is needed, or wanted, on the associations that point at these rows; the
+  database cascade is the only deletion path.
+
+### Negative
+
+- Code that needs such rows gone has to delete a parent and let the cascade do it. Removing an
+  approval's quorum links, for instance, means deleting the approval — the obvious
+  `approval.quorums.destroy_all` raises.
+- Enforcement is application-level. A host that wants it below the application adds `DO INSTEAD
+  NOTHING` rules itself; see [docs/08_events_and_notifications.md](../08_events_and_notifications.md).

data/docs/adr/0008-staged-multi-quorum-schema.md

@@ -0,0 +1,43 @@
+# ADR-0008: Model staged, multi-quorum approval from the first migration
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+The common case is "two people with this permission must approve". The cases that arrive later are
+"one Admin **or** two Owners", "one Admin **and** two Owners, then a Director", and "only these two
+named people". A `required_approvals` integer on the request row expresses the first and none of the
+others.
+
+Retrofitting stages onto a shipped gem means a schema migration in every host application, plus a
+data migration for every request in flight.
+
+## Decision
+
+The schema is staged and multi-quorum from the first migration. A request has ordered **stages**; a
+stage has one or more **quorums**; a quorum is a threshold plus an eligibility set, expressed as
+permission rows (permission × actor type, independently nullable) and named-actor rows.
+
+- Stages are always sequential. Parallelism within a step is one stage holding several quorums;
+  ordered groups are consecutive stages. There is no request-level mode column.
+- A stage's `satisfied_by` is `any_quorum` or `all_quorums`. One word is the whole difference
+  between "OR" and "AND".
+- Counting approvals is the only rule. There is no rule column and no expression language.
+
+A flat 1-of-N request is simply a request with one stage holding one quorum.
+
+## Consequences
+
+### Positive
+
+- Every workflow shape the gem intends to support is already representable; later milestones add the
+  declaration syntax and the evaluation, not tables.
+- Approval policy is never duplicated onto the request row. The stage and quorum rows *are* the
+  frozen snapshot ([ADR-0007](0007-append-only-audit-trail.md)).
+
+### Negative
+
+- Five tables where one integer column would have served the common case, and four joins to answer
+  "can this person approve?".
+- Creating a request writes a small graph rather than a row.

data/docs/adr/0009-host-owned-schema.md

@@ -0,0 +1,43 @@
+# ADR-0009: Let the host own the schema as an ordinary migration
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+An engine with tables has to get them into the host's database. The alternatives are to manage the
+schema from inside the engine — migrating on boot, or keeping a private migration path — or to hand
+the host a migration and let it run the same way as every other migration in the application.
+
+Engine-managed schemas are opaque: they do not appear in the host's `schema.rb`, do not roll back
+with the host's own `db:rollback`, and change the database as a side effect of deploying a gem
+version.
+
+## Decision
+
+The gem ships a migration template. It is copied into the host's `db/migrate` and is thereafter the
+host's file, run, rolled back and reviewed like any other. The gem never creates, alters or migrates
+a table at runtime.
+
+Two rules hold inside that migration:
+
+- **No foreign key points at a host table**, and none ever will
+  ([ADR-0003](0003-actor-references-as-triples.md)).
+- Every foreign key *between* gem tables is `ON DELETE CASCADE`, so deleting a request removes its
+  whole graph in one statement.
+
+## Consequences
+
+### Positive
+
+- The schema is visible in code review, in `schema.rb`, and in whatever migration tooling the host
+  already uses.
+- It rolls back cleanly to zero and migrates straight back up, and leaves the host's own tables
+  untouched when it does — both asserted by the suite.
+- Installing the gem changes no data until someone runs a migration.
+
+### Negative
+
+- A host that installed an earlier version has to take later schema changes as further migrations,
+  which the gem must ship and version carefully.
+- A host can edit its copy. Divergence is possible and undetectable from inside the gem.

data/docs/adr/0010-operations-must-be-declared.md

@@ -0,0 +1,57 @@
+# ADR-0010: Require every operation to be declared in a registry
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+Execution eventually has to turn a stored `operation_key` into a real method call. Resolving that
+from the strings on the request row means `constantize` plus `public_send` on data, which turns any
+endpoint that can write a row into remote code execution.
+
+The related question is where approval policy comes from. If the caller passes thresholds and
+permissions to `request!`, then policy is caller input, and every call site can get it wrong.
+
+## Decision
+
+A host declares its operations up front:
+
+```ruby
+ChangeRequests.operations.define "members.update_roles" do |op|
+  op.version = "2026-09-11"
+  op.service = "Members::UpdateRoles"
+  op.approvals permissions: %w(member_admin), required: 2
+end
+```
+
+- The registry is the **dispatch allowlist**. Execution resolves `operation_key → (service,
+  method_name)` from the declaration, never from the stored strings, which are audit data only.
+- **Approval policy comes from the declaration**, so every call that raises a request is identical
+  no matter how elaborate the workflow is.
+- The resolved workflow is **frozen onto the request at creation** ([ADR-0008](0008-staged-multi-quorum-schema.md)).
+  Editing an operation never reaches a request already in flight.
+- `op.version` is mandatory and is validated at declaration time, so the initializer's own line
+  number reports the mistake.
+- `operations[key]` returns **nil** rather than raising. An undeclared operation is a refusal each
+  guard words for itself — commenting on a stranded request stays open, everything else does not.
+
+`op.approvals` *describes* a workflow; creating a request is what materialises it into rows.
+
+## Consequences
+
+### Positive
+
+- A stored string never reaches `constantize`, so the hole stays closed even if a careless endpoint
+  lets someone write a row.
+- What a request will invoke is legible from the row itself, not only from live configuration.
+- Removing a declaration is reversible: the requests it strands refuse and become invisible, and
+  nothing is destroyed until someone runs the cleanup task deliberately.
+
+### Negative
+
+- Hosts must declare operations before using them. This is the one thing the gem asks that the
+  obvious alternatives do not.
+- The registry is process-global mutable state, which the test suite has to isolate per example.
+- Today the registry carries the declaration attributes and the `op.approvals` shorthand only; the
+  full workflow DSL, boot-time verification and `ChangeRequests.request!` arrive with a later
+  milestone.

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

@@ -0,0 +1,36 @@
+# ADR-0011: Attribute gem-originated actions to a System sentinel actor
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## 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
+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
+forgot to record it" indistinguishable.
+
+## Decision
+
+`ChangeRequests::SYSTEM_ACTOR` is a frozen triple, `{ type: "System", id: "system", label:
+"System" }`, written into the actor columns like any other actor
+([ADR-0003](0003-actor-references-as-triples.md)). Columns that may carry it opt in explicitly;
+`System` is otherwise not an acceptable actor type.
+
+The id is the non-castable string `"system"`, not `"0"`. Actor ids share a string column with host
+classes that may legitimately have string primary keys, and `"0"` is a value one of them could hold.
+
+## Consequences
+
+### Positive
+
+- Every event has an actor, and readers need no null branch.
+- `System` never appears in `config.actor_types`, so it cannot be mistaken for a registered class,
+  and no host record can collide with its id.
+
+### Negative
+
+- A host whose own actor class is literally named `System` cannot register it.
+- The sentinel is a magic value, and the columns that accept it have to say so one by one.

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

@@ -0,0 +1,40 @@
+# ADR-0012: Declare the whole error taxonomy before raising any of it
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+Hosts rescue this gem's errors in one place — typically `rescue_from ChangeRequests::Error` in a
+controller, with finer branches for the cases they handle specially. That code depends on the
+*ancestry* of each error class, not just its name. Introducing `NotApprovable` in one milestone as a
+`StandardError` and re-parenting it under `TransitionError` in the next silently changes which
+`rescue` clause catches it in every host that upgraded.
+
+## Decision
+
+`errors.rb` declares the complete hierarchy up front, including errors no milestone raises yet.
+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
+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.
+
+Errors raised for unsupported operations rather than refused domain transitions stay in ActiveRecord's
+taxonomy; see [ADR-0007](0007-append-only-audit-trail.md).
+
+## Consequences
+
+### Positive
+
+- A host's `rescue` clauses keep meaning the same thing across gem versions.
+- The taxonomy doubles as a specification of what can go wrong, readable in one file.
+- Guard and command cannot disagree about why something was refused.
+
+### Negative
+
+- Classes exist that nothing raises yet, which reads as dead code until the milestone that uses them
+  lands.
+- The reason symbols are now public API and have to be versioned as carefully as the class names.

data/docs/adr/0013-json-runtime-pin.md

@@ -0,0 +1,37 @@
+# ADR-0013: Pin `json` to `~> 2.7` as a runtime dependency
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+json 3.0 removed the positional-options form of `JSON.parse(source, options)`. ActiveSupport 8.1
+still calls it that way, and json 3 is the default bundled version under Ruby 4. The result is that
+**every `jsonb` read raises** `ArgumentError: wrong number of arguments (given 2, expected 1)` from
+three frames inside ActiveSupport — with no hint that a gem version is the cause.
+
+The gem stores `payload` and `payload_labels` as `jsonb`, so this is not an edge case: it breaks
+reading any request at all.
+
+## Decision
+
+`change_requests.gemspec` declares `spec.add_dependency "json", "~> 2.7"`.
+
+A development pin in the `Gemfile` was the first attempt and was not enough: it protects the gem's
+own suite and nobody else, and it does not even cover the gem's own matrix gemfiles, which inherit
+nothing from the root `Gemfile`. A runtime dependency is pulled in by the `gemspec` directive, so it
+constrains the gem's suite, every matrix gemfile and every host.
+
+## Consequences
+
+### Positive
+
+- A host cannot resolve this gem onto a json that breaks it.
+- The constraint is declared once, where the rest of the gem's requirements live.
+
+### Negative
+
+- The gem constrains a dependency it does not itself use, on behalf of ActiveSupport. It is a
+  workaround for someone else's incompatibility and should be removed once ActiveSupport stops
+  calling `JSON.parse` positionally.
+- A host that needs json 3 for another gem has a genuine conflict and no way around it.

data/docs/adr/0014-executable-architecture-rules.md

@@ -0,0 +1,45 @@
+# ADR-0014: Enforce the architectural boundaries executably
+
+- **Status:** Accepted
+- **Date:** 2026-09-11
+
+## Context
+
+[ADR-0001](0001-headless-domain-core.md) is only true while it stays true. One `Rails.logger` in a
+domain file, one `ActiveJob` reference outside a `defined?` guard, and the headless guarantee is
+gone — with nothing failing, because the gem's own suite loads Rails for the dummy application and
+would never notice.
+
+The same applies to the guarantees that only exist at a process boundary: that requiring the gem
+*without* Rails defines no engine, and that requiring it *with* Rails does.
+
+## Decision
+
+Two mechanisms, both wired into `rake ci`:
+
+- **Static.** `Archspec.rb` states the boundaries as executable rules: every file under
+  `lib/change_requests/` except `engine.rb` belongs to a `:domain` component that cannot reference
+  `Rails`, `ActionController`, `ActionView`, `ActionDispatch` or `ActiveJob`, and cannot use the
+  `:engine` component. New directories are added to the component as they appear, so a file outside
+  the rules is a visible omission rather than a silent exemption.
+- **Runtime.** Guarantees that depend on what a process loaded are asserted in **subprocesses**: a
+  probe that boots a real Rails application and one that never requires Rails, each reporting facts
+  the parent asserts. The isolation is the process, not the CI job.
+
+`rake ci` runs RuboCop, archspec, Brakeman, the specs and a CVE check. CI runs the same tasks in at
+most four jobs.
+
+## Consequences
+
+### Positive
+
+- The boundary fails a build rather than being discovered by a host in production.
+- The rules carry their rationale, so the check explains itself when it fires.
+- Deliberate exceptions are per-line and annotated, which makes them countable.
+
+### Negative
+
+- A static analyser cannot see dynamic references, and reports a number of unresolved constants and
+  unknown receivers it simply cannot judge.
+- Subprocess probes are slower than ordinary examples and harder to debug, since a failure arrives
+  as a string of reported facts rather than a stack trace.

data/docs/adr/README.md

@@ -0,0 +1,25 @@
+# Architecture Decision Records
+
+One record per significant architectural choice: its context, the decision, and what it costs.
+
+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.
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| [0001](0001-headless-domain-core.md) | Keep the domain core headless | Accepted |
+| [0002](0002-mountable-engine-with-isolated-namespace.md) | Ship the Rails layer as a mountable engine with an isolated namespace | Accepted |
+| [0003](0003-actor-references-as-triples.md) | Reference host actors by a (type, id, label) triple | Accepted |
+| [0004](0004-uuid-primary-keys.md) | Use uuid primary keys for every gem-owned table | Accepted |
+| [0005](0005-string-states-with-check-constraints.md) | Store states as strings with CHECK constraints, not PostgreSQL enums | Accepted |
+| [0006](0006-creation-time-immutability.md) | Enforce creation-time immutability in the gem, not with `attr_readonly` | Accepted |
+| [0007](0007-append-only-audit-trail.md) | Make the audit trail and the eligibility rows append-only | Accepted |
+| [0008](0008-staged-multi-quorum-schema.md) | Model staged, multi-quorum approval from the first migration | Accepted |
+| [0009](0009-host-owned-schema.md) | Let the host own the schema as an ordinary migration | Accepted |
+| [0010](0010-operations-must-be-declared.md) | Require every operation to be declared in a registry | Accepted |
+| [0011](0011-system-sentinel-actor.md) | Attribute gem-originated actions to a System sentinel actor | Accepted |
+| [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 |