support_desk 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d7e90a546ededcbf2f0f13d30a2929655e0d6bb343f11d114b0e539b8985bfb
-  data.tar.gz: 502d37cedab338e5f42db97b021ed01dd8ee46844600fc31d3240e9a1a09597c
+  metadata.gz: 66ba1a32f86acca1b4068bbca4091fcb16c4e6840a9d57ae5dc44bea25572ea2
+  data.tar.gz: 2433e492636e42eeffde1652a2c7d21915267c6f0a9180bea8bb010d902cdfad
 SHA512:
-  metadata.gz: fae5879d3023eed0f45c24e275bf63fdaf5ac2f8e982a7d6b9ea6c9db4afe12036025c6ef20a1280031456978908414849719fb9ea28a6d53d5dd47a3c6995aa
-  data.tar.gz: 9e8e5df4a7e7f836c297a3509d4c2d23111a6f9365fdd34208e410db11e249aa0445c515fe19421efa4f883b43503cf65bc32efc207007ff46a55d9102b8a470
+  metadata.gz: ac1246120f4c2aa2763f81866006f054e0dfd14901d42120ddc25d754b08dad350b1627552faaa9e4fd62d37a50d785eeae9abe6dab1c5dc9adbb9f9bb44acd1
+  data.tar.gz: 66fca7c4ddad8c9b41358448ec24beda2a3dcd9bade8bd373fe7433a565700d500c212f863c1755048faa7dd803c79c1fa92d3fb0b029a072322d1eff6672994

data/CHANGELOG.md

@@ -4,6 +4,135 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - Unreleased
+
+### Fixed
+
+- Persist message-registration receipts atomically with clocks and turn revisions.
+  A new message with an earlier timestamp or smaller UUID is no longer dropped
+  as a replay. It invalidates the turn and triggers requester notifications and
+  handoff detection once, without rewinding clocks. This also fixes human-only
+  desks; no assistant configuration is needed to encounter the old defect.
+- Recovery discovers unregistered replies on closed cases and honors the desk's
+  reopen/locked policy. Repair also runs when the assistant is disabled; only
+  actual assistant dispatch requires one to be configured.
+- Public assistant assignment, release and reply refuse `turn: :current`.
+  Internal outreach and seat-taking use private paths and actual tokens.
+- Default Chats signatures render assistant messages using per-message
+  disclosure snapshots, including old 0.3.0 messages with provenance but no
+  assistant-row snapshot. Rename, mode change and flag-off do not erase old
+  disclosure. Human replies and approved drafts keep human signatures, and host
+  signature overrides remain authoritative. Transcript names are snapshotted
+  for new messages; older ones use their stored display name.
+- Correct the README signature override to preserve the human fallback.
+
+### Upgrade
+
+Run `rails generate support_desk:upgrade` and migrate **with support writes paused
+and all old web/jobs drained**. The new receipt table follows the existing ticket
+and message ID types and seeds historical messages up to the old role clocks.
+Old clocks cannot reveal lost callbacks behind that baseline: review suspect
+historical cases before resuming. Only 0.3.2 processes may write after cutover.
+See README for recovery, rollback limitations and the unchanged SQLite caveat.
+No gem publication or deployment is performed by this change.
+
+## [0.3.1] - 2026-09-19
+
+**Hardening the assistant, after an adversarial review of 0.3.0.** Nine
+defects, every one of them in the concurrency, recovery and kill-switch
+guarantees the release advertised rather than in what a green suite
+covered. Nothing here changes what an assistant may do; it changes what
+can happen to a case while she is doing it. `assign!` and `release!` take
+a `turn:` when `by:` is an assistant — the one API change — and a host
+with no assistant is untouched.
+
+### Fixed
+
+- **A customer's next question can no longer be answered around (R1).**
+  Reconciliation is a `SELECT`, and a requester never takes the case's row
+  lock, so a question could commit between the answer reading the case and
+  the answer writing to it: she replied to the previous one, and a human
+  approved a proposal from a page that predated the new one — `seen_turn`
+  was not evidence that the reviewer had seen the last committed message.
+  Every speaking path now takes the ticket's row lock and then the
+  conversation row chats updates inside every message insert, before
+  reconciling. The lock order is ticket → conversation everywhere, and it
+  is written down. **The guarantee is a row lock, so it holds on PostgreSQL
+  and MySQL and not on SQLite**, which has no row locks and whose WAL
+  snapshot reads straight through an open write transaction: a desk with an
+  assistant belongs on PostgreSQL or MySQL, and `doctor` now warns when it
+  is not.
+- **A seat is decided under the lock (R2).** `assign!` asked whether
+  anybody held the case, and whether she could hold it, *before* the
+  transition acquired the row. No threads were needed to break it: load an
+  unassigned case into one instance, give it to a person through another,
+  and the first instance took the seat from them. A topic cap or a pause
+  committed while a take waited for the lock was read too late in the same
+  way.
+- **A lost registration is repairable (R3).** A requester message that
+  committed while the process that should have registered it died left a
+  turn nothing could ever consume: reconciliation happened inside the
+  candidate answer's savepoint, the bumped revision made that very answer
+  stale, and the `StaleTurn` rolled the repair back with it — for ever,
+  while the clocks said `awaiting_requester` so no idle query could see the
+  case. The fold is now its own committed step, and
+  `redispatch_assistant_turns!` looks for unregistered messages before it
+  looks at clocks.
+- **Messages that share an instant no longer deadlock the turn (R4).** The
+  unseen-message test was "its id is not the one the clock was set from",
+  so every other message on that timestamp read as new: reconciliation
+  folded an already-registered one in again, bumped the revision, and made
+  the answer that discovered it stale. The retry did the same thing. "Seen"
+  is now the pair `(created_at, id)` compared in chats' own transcript
+  order, by the same rule in Ruby and in SQL.
+- **The silent sweep rechecks before it escalates (R5).** Its predicates
+  were true when it SELECTED its candidates. A person who answered, took
+  the case or reset the clock in between lost anyway: the case was marked
+  human-required, its priority went up, and the customer was told a person
+  was coming — on a case that already had one.
+- **Stranded seats come back (R6).** `deactivate!` promised the sweep would
+  release her cases; the sweep only ever visited configured assistants with
+  a `responds_within`, and only cases already overdue. An assistant with no
+  promise kept her seat for ever, and one removed by the documented kill
+  switch — which takes her configuration away — was not visited at all,
+  while the doctor's assistant checks returned early on exactly that state.
+  `SupportDesk.reclaim_assistant_seats!` (and `rake
+  support_desk:reclaim_assistant_seats`) reads the seats that exist.
+- **Running out of turns tells the host (R7).** The budget branch wrote the
+  `escalated` event, released her seat and posted the public hand-off line,
+  but only the outer `escalate!` published `:ticket_escalated` — so a
+  host's "a person is needed here" notifier never heard about a
+  conversation that ran out of turns. One private method now publishes it
+  for every hand-off.
+- **Disclosure on old messages stops moving (R8).** The requester-facing
+  signature resolved live configuration, so taking her out of the
+  initializer rewrote "— Rose · asistente virtual" into "— Rose" on
+  messages nobody had touched. Her name and mode are snapshotted onto her
+  own row and read back from it when nothing declares her any more. A
+  rename still renames history, deliberately; the README shows the
+  `Chats.config.message_signature` lambda for hosts that want each bubble
+  frozen.
+- **The kill switch is read after the wait (R9).** Eligibility was checked
+  before the case's row lock, and the policy then read `active?` off that
+  same stale copy, so an already-seated assistant whose job queued behind a
+  busy case could still speak after `deactivate!` had committed. Every verb
+  resolves her under the lock now, from the row. The ordinary in-flight
+  window — a switch that commits after that read — is documented rather
+  than claimed away.
+
+### Changed
+
+- `Ticket#assign!` and `Ticket#release!` take `turn:`. It is REQUIRED when
+  `by:` is an assistant (`ArgumentError` when omitted, `StaleTurn` when
+  stale) and ignored for a person, whose calls are unchanged.
+- `SupportDesk.release_silent_assistants!` runs
+  `reclaim_assistant_seats!` first, and its count includes what that
+  reclaimed.
+- The doctor's assistant invariants run whenever an assistant ROW exists,
+  not only while one is configured.
+- `Ticket.with_unregistered_requester_messages` — the scope behind the
+  repair half of redispatch.
+
 ## [0.3.0] - 2026-09-19
 
 **A machine can answer, and a person still owns every word it sends.** An

data/README.md

@@ -942,6 +942,13 @@ one raises `SupportDesk::StaleTurn` and writes nothing. That one integer is
 also why this gem has no idempotency keys, no claim rows and no leases —
 "is this still the case you read?" is already answered.
 
+Every verb of hers takes it, and that includes taking and giving back the
+seat: `assign!(to: rose, by: rose, turn:)` and `release!(by: rose, turn:)`
+require it when `by:` is an assistant (an omitted turn is an
+`ArgumentError`, a stale one a `StaleTurn`), because a run that finished
+after the case moved on must not release the seat a newer one took. A
+**person's** calls are unchanged and take no turn.
+
 Two consequences worth knowing:
 
 - Check `ticket.assistant_turn == turn` in your job **before you spend
@@ -949,6 +956,34 @@ Two consequences worth knowing:
 - A retry after a committed action is a `StaleTurn`, and that is correct:
   the work was done. Generated jobs `discard_on` it.
 
+#### Ticket, then conversation
+
+A turn is only as good as the reconciliation behind it, and reconciliation
+is a `SELECT`: on its own it cannot exclude a message that commits a
+millisecond later. Your customer never takes the case's row lock — they
+press send, and chats writes a message.
+
+What chats *does* take is the **conversation row**: every message insert
+updates `chats_conversations` inside its own transaction. So every path
+that speaks takes the ticket's row lock and then that row, before
+reconciling. A question already in flight holds it, so we wait for it and
+the turn goes stale; a question that starts after we hold it waits for us
+and raises a turn of its own. **The order is always ticket → conversation**,
+in this gem and in anything you add to it.
+
+What that does not cover: a message whose `INSERT` was already stamped when
+we won the row is still stamped earlier than the answer, so a transcript can
+show a question above an answer that did not address it. That is a
+genuinely simultaneous send, and its own turn follows.
+
+> [!IMPORTANT]
+> **This is a row lock, so it is PostgreSQL and MySQL.** SQLite has none:
+> it serializes writes, and in WAL mode a reconciliation `SELECT` reads the
+> last committed snapshot straight through a requester's open write
+> transaction, so a question committing behind an answer is still missed
+> there. Run PostgreSQL or MySQL for a production desk with an assistant —
+> `SupportDesk.doctor` warns when you haven't.
+
 ### Proposals in the console
 
 A pending proposal renders above the composer with its confidence, its
@@ -1020,6 +1055,32 @@ the turn and the whole policy that allowed it, `ticket.export` labels it
 marks it for staff. What a customer is told is a product decision; what your
 records say a machine wrote is not.
 
+**Historical disclosure is captured per message.** The default Chats signature
+renderer uses the assistant name and disclosure stored when the message was
+sent. Renaming, changing mode or removing configuration does not rewrite old
+signed bubbles. Human replies and human-approved drafts retain their normal
+human signatures. The assistant row snapshot is a fallback for legacy messages
+without provenance; their original disclosure cannot be reconstructed if it
+was never stored.
+
+A host's `Chats.config.message_signature` override remains authoritative. If
+you customize it, preserve the human fallback as well as the assistant snapshot:
+
+```ruby
+Chats.configure do |config|
+  config.message_signature = lambda do |message|
+    stamp = message.metadata["support_desk"]
+    name = if stamp.is_a?(Hash) && stamp["kind"] == "ai" && stamp["signed"] == true &&
+              stamp["display_name"].is_a?(String) && stamp["display_name"].present?
+      stamp["display_name"]
+    else
+      Chats.display_name_for(message.author)
+    end
+    I18n.t("chats.message.signature", name: name)
+  end
+end
+```
+
 ### Humans outrank
 
 - A person may answer a case she holds under **every** `reply_policy`.
@@ -1071,8 +1132,27 @@ whatever she would have said. `redispatch_assistant_turns` re-emits the turn
 for cases nobody acted on, which is safe precisely because the turn is
 consumed by the first action and every later one is a `StaleTurn`.
 
-`rake support_desk:assistant_status` reads and writes nothing, and is the
-line to put in a deploy check. `SupportDesk.doctor` covers the same ground
+`release_silent_assistants` runs `SupportDesk.reclaim_assistant_seats!`
+first, and you can run that on its own
+(`rake support_desk:reclaim_assistant_seats`). It is a different question
+from silence: it reads the **seats that exist** rather than the assistants
+this process happens to have configured, and gives back every one whose
+holder is switched off, no longer declared, or no longer allowed to hold a
+case — with no `responds_within` and no overdue clock anywhere in it. That
+is what makes `deactivate!` and a flag flipped off actually release her
+cases, and it is why the doctor's seat checks keep running when the
+configuration is gone.
+
+`redispatch_assistant_turns` also repairs before it decides: a requester
+message whose registration was lost after its commit leaves the clocks
+describing a case that no longer exists, so the task looks for unregistered
+**messages** and not only for idle clocks. The repair commits on its own,
+which is what makes a dead process followed by nothing but this task end in
+an actionable turn.
+
+`rake support_desk:assistant_status` reports current counts without changing
+tickets. Resolving configured assistants may create their identity rows or
+refresh their name/disclosure snapshots. `SupportDesk.doctor` covers the same ground
 with verdicts.
 
 ### What the model sees
@@ -1166,7 +1246,8 @@ acts_as_support_agent kind: :ai                                 # validated; see
 SupportDesk.assistant(key = nil)        # the Assistant record, memoised; nil when none is configured
 SupportDesk.reset_assistants!
 SupportDesk.ai_actor?(record)
-SupportDesk.release_silent_assistants!            # → Integer
+SupportDesk.release_silent_assistants!            # → Integer (runs reclaim_assistant_seats! first)
+SupportDesk.reclaim_assistant_seats!              # → Integer; seats she may no longer sit in
 SupportDesk.redispatch_assistant_turns!(older_than: 1.minute)   # → Integer
 ```
 
@@ -1176,7 +1257,7 @@ SupportDesk.redispatch_assistant_turns!(older_than: 1.minute)   # → Integer
 |---|---|
 | `SupportDesk::Assistant.for(key)` / `.active` | found or created; the on-duty scope |
 | `config` / `configured?` | her slice of the configuration; whether anything still declares her |
-| `name` `avatar` `autonomy` `disclosure` `max_turns` `responds_within` `may_open_conversations?` | read through the configuration, with safe answers when it is gone |
+| `name` `avatar` `autonomy` `disclosure` `max_turns` `responds_within` `may_open_conversations?` | read through the configuration; `name` and `disclosure` fall back to the snapshot on her row, the rest to the safe answer |
 | `disclosed?` `signs?` `notice?` | the mode, as predicates |
 | `disclosed_name` `display_name` `to_s` `support_agent_name` `support_agent_avatar` | what a requester sees |
 | `on_duty?` `support_capacity` | the agent contract |
@@ -1201,6 +1282,8 @@ assistant" it was).
 respond!(body, by:, turn:, files:, confidence:, sources:, metadata:, request:)   # → Outcome
 draft!(body, by:, turn:, …)                                                       # → Draft
 escalate!(by:, reason:, summary:, turn:, request:)
+assign!(to:, by:, reason:, note:, request:, turn:)   # turn: required when by: is an assistant
+release!(by:, reason: :released, request:, turn:)    # idem
 request_human!(by:, request:)          # by: must be the requester
 pause_assistant!(by:, reason:) / resume_assistant!(by:)
 
@@ -1213,6 +1296,7 @@ drafts   pending_draft   notes
 # scopes
 held_by_assistants   held_by_humans   needs_human   assistant_paused   assistant_capped
 resolved_by_assistant   with_pending_draft   assistant_idle_since(time)
+with_unregistered_requester_messages
 ```
 
 Columns: `assistant_revision`, `last_requester_message_id`,
@@ -1288,12 +1372,13 @@ the count is non-zero.
 `support_human_door(ticket)` helper.
 
 **Rake** — `support_desk:release_silent_assistants` ·
+`support_desk:reclaim_assistant_seats` ·
 `support_desk:redispatch_assistant_turns` (`OLDER_THAN=60`) ·
 `support_desk:assistant_status`.
 
 **Doctor** — `assistants (config)` · `assistant turn subscriber` ·
 `assistant authorship` · `assistant silence` · `assistant seats` ·
-`assistant idle turns` · `drafts` · `ai agents without policy`.
+`assistant idle turns` · `drafts` · `ai agents without policy` · `message registrations`.
 
 **Test helpers**
 
@@ -1310,10 +1395,54 @@ the count is non-zero.
 | `with_assistant_config(key = nil, **overrides) { … }` | |
 | `with_topic_assistant_cap(path, level) { … }` | rebuilds the frozen tree with one cap |
 
-### Upgrading to 0.3
+### Upgrading to 0.3.2 (including hosts without assistants)
+
+0.3.2 adds `support_desk_message_registrations`, an internal receipt per text
+message. A receipt, written with the ticket clocks and revision in one
+transaction, distinguishes a replay from an unseen message. Timestamp and UUID
+order are not evidence of delivery. Every unseen requester message invalidates
+the turn, notifies the host and runs handoff detection once, even if its timestamp
+is older; the SLA timestamps themselves never move backwards.
+
+**This upgrade requires a drained cutover; it is not rolling-safe.** The table
+is additive, but old processes cannot write receipts.
+
+1. Pause support writes and drain old web requests and jobs. Keep the assistant
+   disabled throughout the cutover.
+2. Run `rails generate support_desk:upgrade`, inspect the new migration, then
+   `rails db:migrate` while writes remain paused. Fresh installs get the same
+   migration from `support_desk:install`.
+3. The migration seeds existing text messages at or before each role's old
+   clock as the historical baseline. Messages beyond those clocks remain
+   discoverable by recovery. **Old data cannot prove whether a message behind
+   the clock lost its callback.** Review suspect historical cases explicitly;
+   the migration does not replay old notifications or reopen history en masse.
+4. Start only 0.3.2 processes. Run `SupportDesk.doctor` and
+   `SupportDesk.redispatch_assistant_turns!` before resuming support traffic.
+   Recovery checks closed cases as well: `:reopen_on_reply` reopens them, while
+   `:locked` preserves closure and dispatches no model work. Registration repair
+   also runs on desks with no assistant configured.
+5. Resume writes. An assistant rollout still requires its own staging checks
+   and disclosure decision. The serialization guarantee still requires
+   PostgreSQL/MySQL; SQLite does not acquire row locks.
+
+Do not roll back to an old writer while serving traffic: it would leave missing
+receipts. If a rollback is necessary, pause and drain first, keep the receipt
+table, and re-establish the historical baseline before a later upgrade. Removing
+a receipt deliberately permits processing that message again; it is an internal
+recovery action, not a normal host API.
+
+Public assistant `turn:` arguments must be the observed opaque token. Symbols
+such as `:current` are refused; private outreach and automatic seat-taking do
+not expose a public bypass. No new host-facing registration API is required.
+
+### Historical upgrade from 0.2 to 0.3.0
+
+The following describes the original assistants migration. When installing the
+current release, also follow the 0.3.2 cutover above.
 
 ```bash
-rails generate support_desk:upgrade   # copies the additive assistants migration
+rails generate support_desk:upgrade   # current releases also copy the receipt migration
 rails db:migrate
 ```
 
@@ -1464,10 +1593,13 @@ supportable), `find_requester` (callable, one argument), `engine mount`,
 (no half-NULL `opened_by`; warns on legacy NULL rows and names the backfill
 task), `awaiting` (agrees with the transcript), `references` (unique).
 Assistants (only where one is configured): `assistants (config)`,
-`assistant turn subscriber`, `assistant authorship`, `assistant silence`,
-`assistant seats`, `assistant idle turns`, `drafts`, and `ai agents without
-policy` — which warns about any host class declared `kind: :ai`, since every
-support write by it is refused.
+`assistant turn subscriber`, `assistant serialization` — which warns when
+the adapter takes no row locks, because the turn rests on them —
+`assistant authorship`, `assistant silence`, `assistant seats`, `assistant
+idle turns`, `drafts`, and `ai agents without policy`, which warns about any
+host class declared `kind: :ai`, since every support write by it is refused.
+The seat and draft checks also run once she is no longer configured, since
+that is exactly when a seat gets stranded.
 
 ## Compatibility
 
@@ -1536,6 +1668,7 @@ SupportDesk.desk(key = :default)       # the Desk record, found or created, memo
 SupportDesk.assistant(key = nil)       # the Assistant record, memoised; nil when none is configured
 SupportDesk.reset_assistants!          SupportDesk.ai_actor?(record)
 SupportDesk.release_silent_assistants!            # the net under a dead harness (schedule it)
+SupportDesk.reclaim_assistant_seats!              # seats an assistant may no longer sit in
 SupportDesk.redispatch_assistant_turns!(older_than: 1.minute)
 SupportDesk.find_topic("billing/invoice")
 SupportDesk.on(event, key: nil) { … }  SupportDesk.off(event, key)

data/lib/generators/support_desk/install_generator.rb

@@ -44,6 +44,12 @@ module SupportDesk
                            File.join(db_migrate_path, "add_assistants_to_support_desk.rb")
       end
 
+      def create_message_registrations_migration
+        migration_template "create_support_desk_message_registrations.rb.erb",
+                           File.join(db_migrate_path, "create_support_desk_message_registrations.rb")
+      end
+
+
       # The annotated initializer — every setting the gem has, with what it
       # means and what it defaults to.
       def create_initializer
@@ -90,9 +96,9 @@ module SupportDesk
         say "  #   routing(/^support@/i => :support_desk)"
 
         say "\n  Already installed and bumping the version? 'rails g support_desk:upgrade' copies"
-        say "  only the migrations the new version needs (0.2.0: who opened the case), and"
-        say "  nothing you own. Follow the CHANGELOG's drained cutover: migrate, pause"
-        say "  support traffic, drain old web/workers, backfill, then serve only 0.2."
+        say "  only the migrations the new version needs (including 0.3.2 receipts), and"
+        say "  nothing you own. Follow the README drained cutover: pause support writes,"
+        say "  drain old web/workers, migrate, then start only the new version."
 
         say "\n  Assistants (0.3): when a machine should answer first, 'rails g support_desk:assistant"
         say "  Rose --disclosure signature' writes the harness and prints the stanza. Read the"

data/lib/generators/support_desk/templates/create_support_desk_message_registrations.rb.erb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Stop support writes and drain old web/jobs before migrating. Old processes
+# cannot write receipts. Existing messages at/before the legacy clocks form
+# the historical baseline; messages ahead of those clocks remain repairable.
+# A pre-upgrade lost callback behind a clock cannot be inferred from old data:
+# review historical suspect cases before resuming writes (see README).
+class CreateSupportDeskMessageRegistrations < ActiveRecord::Migration<%= migration_version %>
+  def up
+    return if table_exists?(:support_desk_message_registrations)
+
+    create_table :support_desk_message_registrations, id: false do |t|
+      t.column :message_id, column_type(:chats_messages, "id"), null: false
+      t.column :ticket_id, column_type(:support_desk_tickets, "id"), null: false
+    end
+    add_index :support_desk_message_registrations, :message_id, unique: true, name: "index_sd_registrations_message"
+    add_index :support_desk_message_registrations, :ticket_id, name: "index_sd_registrations_ticket"
+    add_foreign_key :support_desk_message_registrations, :support_desk_tickets, column: :ticket_id, on_delete: :cascade
+    add_foreign_key :support_desk_message_registrations, :chats_messages, column: :message_id, on_delete: :cascade
+
+    execute <<~SQL
+      INSERT INTO support_desk_message_registrations (message_id, ticket_id)
+      SELECT m.id, t.id FROM chats_messages m
+      JOIN support_desk_tickets t ON t.conversation_id = m.conversation_id
+      WHERE m.kind = 'text' AND (
+        (m.sender_type = t.requester_type AND m.sender_id = t.requester_id
+          AND m.created_at <= t.last_requester_message_at)
+        OR (m.sender_type = 'SupportDesk::Desk' AND m.sender_id = t.desk_id
+          AND m.created_at <= t.last_agent_message_at))
+    SQL
+  end
+
+  def down
+    drop_table :support_desk_message_registrations, if_exists: true
+  end
+
+  private
+
+  def column_type(table, name)
+    connection.columns(table).find { |column| column.name == name }.sql_type
+  end
+end

data/lib/generators/support_desk/upgrade_generator.rb

@@ -9,16 +9,14 @@ module SupportDesk
     # bump needs into an EXISTING install. Nothing else: the initializer, the
     # views, the console and the routes you already own stay untouched.
     #
-    # Currently writes the 0.2.0 migration (who opened the case), which is the
-    # SAME template a fresh install runs — one file owns those columns, so a
-    # fresh install and an upgraded one end up with the same schema and the
-    # same rollback. Running this twice writes nothing the second time: the
-    # migration already sitting in db/migrate is identical, and Rails skips it.
+    # Install and upgrade use the same templates for opened_by, assistants,
+    # and message receipts. See the README for the drained receipt cutover;
+    # old writers do not know how to record message identities.
     class UpgradeGenerator < Rails::Generators::Base
       include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
-      desc "Add the migrations a support_desk version bump needs (0.2.0: opened_by, 0.3.0: assistants)"
+      desc "Add the migrations a support_desk version bump needs (opened_by, assistants, message registration receipts)"
 
       # Rails' migration numbering, borrowed from ActiveRecord's generators.
       def self.next_migration_number(dir)
@@ -35,6 +33,12 @@ module SupportDesk
                            File.join(db_migrate_path, "add_assistants_to_support_desk.rb")
       end
 
+      def create_message_registrations_migration
+        migration_template "create_support_desk_message_registrations.rb.erb",
+                           File.join(db_migrate_path, "create_support_desk_message_registrations.rb")
+      end
+
+
       def display_post_upgrade_message
         say "\n🎫 support_desk upgrade migrations copied.", :green
         say "\n  1. Run 'rails db:migrate'. It adds `opened_by` and points every existing"
@@ -53,7 +57,11 @@ module SupportDesk
         say "       rails g support_desk:assistant Rose --disclosure signature"
         say "     writes the harness and prints the stanza, the subscription and the two"
         say "     scheduled tasks. It never edits your initializer."
-        say "  5. See the CHANGELOG for the full list.\n", :green
+        say "  5. 0.3.2 receipts require a drained cutover: pause support writes and stop"
+        say "     old web/jobs, migrate, then start only the new version. Review historical"
+        say "     suspect callbacks before resuming; old clocks cannot prove delivery."
+        say "     Do not roll code back to a writer that cannot record receipts."
+        say "  6. See the CHANGELOG for the full list.\n", :green
       end
 
       private

data/lib/support_desk/doctor.rb

@@ -162,6 +162,14 @@ module SupportDesk
           ok_with("#{SupportDesk.config.assistants.size} assistant(s) configured")
         end
 
+        checks << check("assistant serialization") do
+          next ok_with("no assistant on any desk") if assistant_desks.empty?
+          next warn_with("the turn cannot exclude a requester message committing behind an answer on " \
+                         "SQLite — use PostgreSQL or MySQL") if sqlite?
+
+          ok_with("#{ActiveRecord::Base.connection.adapter_name} takes the row locks the turn rests on")
+        end
+
         checks << check("assistant turn subscriber") do
           next ok_with("no assistant on any desk") if assistant_desks.empty?
           next warn_with("nothing subscribes to :assistant_turn — no harness will ever answer. See the " \
@@ -245,6 +253,12 @@ module SupportDesk
         tables?
 
       checks = [
+        check("message registrations") do
+          next fail_with("run rails g support_desk:upgrade and rails db:migrate before serving support writes") unless
+            MessageRegistration.table_exists?
+
+          ok_with("message registration receipts available")
+        end,
         check("conversations") do
           orphans = Ticket.where(conversation_id: nil).count
           next fail_with("#{orphans} ticket(s) without a conversation") if orphans.positive?
@@ -317,10 +331,13 @@ module SupportDesk
     # and never of the policy's own verdict. A policy cannot page anybody
     # about its own bug.
     def assistant_invariant_checks
-      # Nothing about a feature nobody turned on: a host with no assistant
-      # configured runs not one extra query (I1).
-      return [] if SupportDesk.config.assistants.empty?
       return [] unless assistants_migrated?
+      # Nothing about a feature nobody turned on (I1) — but "turned on" is
+      # not "configured right now". A host that removed her configuration
+      # still has the seats she is sitting on and the proposals she wrote,
+      # and the checks about THOSE are the ones that matter most on the way
+      # down (R6).
+      return [] if SupportDesk.config.assistants.empty? && !SupportDesk::Assistant.exists?
 
       checks = []
 
@@ -376,6 +393,16 @@ module SupportDesk
       checks
     end
 
+    # Whether this app is on SQLite, which has no row locks: it serializes
+    # writes, and a WAL snapshot reads straight through an open write
+    # transaction. Everything the turn rests on — the ticket's row lock and
+    # the conversation's — buys nothing there, because nothing waits on it.
+    def sqlite?
+      ActiveRecord::Base.connection.adapter_name.match?(/sqlite/i)
+    rescue StandardError
+      false
+    end
+
     # The desks that actually have an assistant, as Desk records.
     def assistant_desks
       SupportDesk.config.desks.each_key.filter_map do |key|

data/lib/support_desk/engine.rb

@@ -33,7 +33,7 @@ module SupportDesk
     SUPPORT_DESK_LIB = File.expand_path("support_desk", LIB_ROOT)
 
     ZEITWERK_IGNORED = %w[
-      version.rb errors.rb events.rb topic.rb topic_tree.rb configuration.rb current.rb macros.rb engine.rb
+      message_signatures.rb version.rb errors.rb events.rb topic.rb topic_tree.rb configuration.rb current.rb macros.rb engine.rb
       console.rb console_routes.rb console_engine.rb
     ].freeze
 
@@ -111,6 +111,11 @@ module SupportDesk
       SupportDesk.subscribe_to_chats!
     end
 
+    initializer "support_desk.message_signatures" do
+      require_relative "message_signatures"
+      Chats.singleton_class.prepend(SupportDesk::MessageSignatures)
+    end
+
     # The checks that need the host's own classes loaded — the requester
     # class, and every `about:` class named in a topic tree. In to_prepare
     # (not an initializer) so they re-run after every code reload, which is

data/lib/support_desk/message_signatures.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The default Chats renderer uses the name/disclosure captured when an
+  # assistant spoke. Host signature overrides remain authoritative. Human
+  # replies (including approved drafts) still use Chats' normal signature.
+  module MessageSignatures
+    def message_signature_for(message)
+      return super if config.message_signature || !message&.signed?
+
+      stamp = message.metadata.is_a?(Hash) && message.metadata["support_desk"]
+      return super unless stamp.is_a?(Hash) && stamp["kind"] == "ai" && stamp["signed"] == true
+
+      name = stamp["display_name"]
+      return super unless name.is_a?(String) && name.present?
+
+      I18n.t("chats.message.signature", name: name)
+    end
+  end
+end