sessions 0.1.3 → 0.2.0

data/docs/research/{01-carhey.md → 01-host-app.md}

@@ -1,6 +1,6 @@
-# CarHey audit: auth, sessions & device detection
+# HostApp audit: auth, sessions & device detection
 
-Read-only audit of `/Users/javi/GitHub/carhey` (Rails 8.1.1, RailsFast, Devise), its native shells `/Users/javi/GitHub/carhey-ios` + `/Users/javi/GitHub/carhey-android`, and (addendum) `/Users/javi/GitHub/licenseseat`. Audited 2026-06-11. All paths relative to each repo root unless absolute. Facts cite `path:line`; anything inferred is marked as such.
+Read-only audit of `/path/to/repos/hostapp` (Rails 8.1.1, RailsFast, Devise), its native shells `/path/to/repos/hostapp-ios` + `/path/to/repos/hostapp-android`, and (addendum) `/path/to/repos/licenseseat`. Audited 2026-06-11. All paths relative to each repo root unless absolute. Facts cite `path:line`; anything inferred is marked as such.
 
 ## Top findings
 
@@ -8,9 +8,9 @@ Read-only audit of `/Users/javi/GitHub/carhey` (Rails 8.1.1, RailsFast, Devise),
 - Admin is a `users.admin` boolean (`db/schema.rb:1260`) gated by `authenticate :user, lambda { |u| u.admin? }` (`config/routes.rb:26`). Single Devise scope; no OmniAuth, no passkeys, no 2FA, no magic links.
 - Session store is Rails' default CookieStore — no `session_store` initializer exists anywhere in `config/` (verified by grep). Sessions are therefore **unenumerable and unrevocable server-side** today.
 - Native apps get silent 1-year remember-me: `remember_hotwire_native_session` (`app/controllers/users/sessions_controller.rb:187-198`) + `config.remember_for = 1.year` (`config/initializers/devise.rb:175`).
-- CarHey already has a world-class **signup-time** device fingerprint: 22 `signup_*` columns on `users` (`db/schema.rb:1306-1322`), populated by `SignupAttribution` (DeviceDetector + UA Client Hints, `app/services/signup_attribution.rb`) and `SignupDisplayMetrics`. It is one-shot — never refreshed at login.
+- HostApp already has a world-class **signup-time** device fingerprint: 22 `signup_*` columns on `users` (`db/schema.rb:1306-1322`), populated by `SignupAttribution` (DeviceDetector + UA Client Hints, `app/services/signup_attribution.rb`) and `SignupDisplayMetrics`. It is one-shot — never refreshed at login.
 - Per-user "what client is this user running NOW" exists as `last_seen_*` columns (`db/schema.rb:1280-1284`), written only by the native JSON API via a race-safe throttled SQL `UPDATE ... WHERE IS DISTINCT FROM` (`app/controllers/api/v1/base_controller.rb:32-57`). Web requests never touch it; one row per user, not per device.
-- Native shells announce themselves via load-bearing UA tokens: Android WebView prefix `"CarHey Android;"` (`carhey-android .../CarHeyApplication.kt:169`), iOS `"CarHey iOS; RailsFast Native iOS;"` (`carhey-ios RailsFast/Core/AppConfiguration.swift:10-12`). Server matches `/\b(?:CarHey\s+Android|Hotwire Native Android|Turbo Native Android)\b/i` (`app/services/signup_attribution.rb:315-324`).
+- Native shells announce themselves via load-bearing UA tokens: Android WebView prefix `"HostApp Android;"` (`hostapp-android .../HostAppApplication.kt:169`), iOS `"HostApp iOS; RailsFast Native iOS;"` (`hostapp-ios RailsFast/Core/AppConfiguration.swift:10-12`). Server matches `/\b(?:HostApp\s+Android|Hotwire Native Android|Turbo Native Android)\b/i` (`app/services/signup_attribution.rb:315-324`).
 - Both shells also stamp **exact** `X-Client-Platform/Version/Build/OS` headers on native JSON calls (Android OkHttp interceptor `NativeHttpClient.kt:47-80`; iOS `NativeHttpClient.swift:12-56`), parsed server-side by `ClientVersionInfo` (`app/controllers/concerns/client_version_info.rb`).
 - **No push notifications anywhere**: no FCM/APNs code in either shell (grep for `UNUserNotificationCenter|registerForRemoteNotifications|Firebase` returned nothing), no device-token tables, no push gems.
 - IP geolocation = `trackdown` 0.2.0, **no initializer** (default `:auto` provider → Cloudflare `CF-IPCountry`/`CF-IPCity` headers), called exactly once in the whole app: synchronously at signup (`app/controllers/users/registrations_controller.rb:45`).
@@ -127,7 +127,7 @@ end
 
 **Server-side detection** is turbo-rails' `hotwire_native_app?` (UA `~ /(Turbo|Hotwire) Native/`; cited in-code at `app/controllers/application_controller.rb:195-196`). Per-platform: `HotwireNativeHelper#hotwire_native_platform` (`app/helpers/hotwire_native_helper.rb:63-69`) checks UA for literal `"Hotwire Native Android"` / `"Hotwire Native iOS"`. Bridge-component capability sniffing parses the UA's `bridge-components: [...]` list (:78-94) — e.g. the toast component decides flash handling at `app/controllers/native/entries_controller.rb:40-45`.
 
-**iOS WebView UA** — prefix built at `carhey-ios/RailsFast/Core/AppConfiguration.swift:10-12`:
+**iOS WebView UA** — prefix built at `hostapp-ios/RailsFast/Core/AppConfiguration.swift:10-12`:
 
 ```swift
 static var userAgentPrefix: String {
@@ -135,29 +135,29 @@ static var userAgentPrefix: String {
 }
 ```
 
-`applicationName` = `CFBundleDisplayName` = `CarHey` (`carhey-ios/project.yml:63`), set via `Hotwire.config.applicationUserAgentPrefix` (`carhey-ios/RailsFast/App/AppDelegate.swift:102`). Per the comment at `AppDelegate.swift:90-93`, the framework appends `"Hotwire Native iOS"`, `"Turbo Native iOS"`, and the bridge-component list — so the effective WebView UA starts `CarHey iOS; RailsFast Native iOS; Hotwire Native iOS; Turbo Native iOS; bridge-components: [...]` followed by the WebKit UA (final composed string is framework behavior — inference from those comments, not observed at runtime).
+`applicationName` = `CFBundleDisplayName` = `HostApp` (`hostapp-ios/project.yml:63`), set via `Hotwire.config.applicationUserAgentPrefix` (`hostapp-ios/RailsFast/App/AppDelegate.swift:102`). Per the comment at `AppDelegate.swift:90-93`, the framework appends `"Hotwire Native iOS"`, `"Turbo Native iOS"`, and the bridge-component list — so the effective WebView UA starts `HostApp iOS; RailsFast Native iOS; Hotwire Native iOS; Turbo Native iOS; bridge-components: [...]` followed by the WebKit UA (final composed string is framework behavior — inference from those comments, not observed at runtime).
 
-**iOS native-JSON UA + headers** — `carhey-ios/RailsFast/Core/NativeHttpClient.swift:12-15,61-72`: headers `X-Client-Platform: ios`, `X-Client-Version` (CFBundleShortVersionString), `X-Client-Build` (CFBundleVersion), `X-Client-OS` (`"iOS \(version)"`), and UA:
+**iOS native-JSON UA + headers** — `hostapp-ios/RailsFast/Core/NativeHttpClient.swift:12-15,61-72`: headers `X-Client-Platform: ios`, `X-Client-Version` (CFBundleShortVersionString), `X-Client-Build` (CFBundleVersion), `X-Client-OS` (`"iOS \(version)"`), and UA:
 
 ```swift
 return "\(applicationName) iOS \(version) (build \(build); iOS \(osVersion); \(resolvedModel))"
 ```
 
-**Android WebView UA** — `carhey-android/.../CarHeyApplication.kt:169`: `Hotwire.config.applicationUserAgentPrefix = "CarHey Android;"`.
+**Android WebView UA** — `hostapp-android/.../HostAppApplication.kt:169`: `Hotwire.config.applicationUserAgentPrefix = "HostApp Android;"`.
 
-**Android OkHttp UA + headers** — `carhey-android/.../ClientHeaders.kt:25-28,66-77`:
+**Android OkHttp UA + headers** — `hostapp-android/.../ClientHeaders.kt:25-28,66-77`:
 
 ```kotlin
-return "CarHey Android $versionName (build $versionCode; Android $osRelease; sdk $sdkInt; $device)"
+return "HostApp Android $versionName (build $versionCode; Android $osRelease; sdk $sdkInt; $device)"
 ```
 
-stamped by an application-level interceptor with `.header()` replace-not-append semantics (`carhey-android/.../NativeHttpClient.kt:47-80`). `ClientHeaders.kt:17-21` documents the **critical contract**: the UA must contain the literal space-separated token `CarHey Android` because the server matches `/\bCarHey\s+Android\b/i` — `SignupAttribution#detect_native_platform` (`app/services/signup_attribution.rb:315-324`) accepts `CarHey Android|Hotwire Native Android|Turbo Native Android` and `CarHey iOS|iPhone|iPad|Hotwire Native iOS|Turbo Native iOS`.
+stamped by an application-level interceptor with `.header()` replace-not-append semantics (`hostapp-android/.../NativeHttpClient.kt:47-80`). `ClientHeaders.kt:17-21` documents the **critical contract**: the UA must contain the literal space-separated token `HostApp Android` because the server matches `/\bHostApp\s+Android\b/i` — `SignupAttribution#detect_native_platform` (`app/services/signup_attribution.rb:315-324`) accepts `HostApp Android|Hotwire Native Android|Turbo Native Android` and `HostApp iOS|iPhone|iPad|Hotwire Native iOS|Turbo Native iOS`.
 
 **Header parsing server-side** — `ClientVersionInfo` concern (`app/controllers/concerns/client_version_info.rb`): platform allow-list `%w[android ios web]`, semver regex, build clamped to Play's 2.1B cap, 64-char OS cap; explicit "spoofable, diagnostics-only, never authorization" doctrine (:7-12). Fallback path delegates to `SignupAttribution` (:66-75). Consumed by `Api::V1::BaseController#touch_last_seen_client` (:32-57) — the throttled, race-safe `update_all` with `IS DISTINCT FROM` predicates that maintains `users.last_seen_*`.
 
 **Session-relevant native routes** (`config/routes.rb:84-95`): `/native/entry` (canonical signed-out bootstrap), `/native/handoff` (auth-success), `/native/auth/welcome` (legacy alias), `/native/configurations/{ios,android}/v1` (server-driven path configuration, version-gated auth sheet/handoff rules in `app/controllers/native/configurations_controller.rb:67-75,196-205,344-352,494`). Native bootstrap defensively consumes **stale remember cookies of now-inactive users** before Warden runs: `consume_inactive_native_remembered_user!` reads `cookies.signed["remember_user_token"]` via `User.serialize_from_cookie` without firing strategies (`app/controllers/application_controller.rb:371-417`) — a subtle Devise+native lifecycle edge any session gem must not break.
 
-**One cookie = one session across surfaces.** Native JSON requests authenticate with the *same Rails session cookie* as the WebView: Hotwire Native syncs WKWebView cookies into `HTTPCookieStorage.shared` after every page load and the iOS URLSession is explicitly configured to use it (`carhey-ios/RailsFast/Core/NativeHttpClient.swift:75-100`, with source links in-code); Android's OkHttp client follows the same posture. Consequence for the gem: a "device" is one shared cookie jar spanning WebView navigations *and* native HTTP calls — per-request UA strings differ (WebView UA vs `ClientHeaders` UA) while the session identity stays constant, so device identity must key off the session/remember cookie, never off the UA.
+**One cookie = one session across surfaces.** Native JSON requests authenticate with the *same Rails session cookie* as the WebView: Hotwire Native syncs WKWebView cookies into `HTTPCookieStorage.shared` after every page load and the iOS URLSession is explicitly configured to use it (`hostapp-ios/RailsFast/Core/NativeHttpClient.swift:75-100`, with source links in-code); Android's OkHttp client follows the same posture. Consequence for the gem: a "device" is one shared cookie jar spanning WebView navigations *and* native HTTP calls — per-request UA strings differ (WebView UA vs `ClientHeaders` UA) while the session identity stays constant, so device identity must key off the session/remember cookie, never off the UA.
 
 **Push device registration: none.** No notification code in either shell, no token model, no `/native` push route. (Verified: zero `UNUserNotificationCenter`/`registerForRemoteNotifications`/Firebase hits in either repo.)
 
@@ -180,7 +180,7 @@ stamped by an application-level interceptor with `.header()` replace-not-append
 
 - **Stack** (`0-overview.mdc`): RailsFast omakase — Postgres, importmaps/no-build, Tailwind 4 + heroicons, Solid Queue/Cache/Cable (no Redis), Kamal deploys behind Cloudflare, AWS SES mail, madmin admin, goodmail emails, `moderate` for T&S. Inline comments must carry rationale + source URLs ("Document as you go").
 - **Quality** (`1-quality.mdc`): DRY/KISS/YAGNI, "the best part is no part", no enterprise architecture, idiomatic Rails, syntactic sugar valued.
-- **Project specifics** (`3-project-specifics.mdc`): mobile-first Hotwire Native hybrid; minimize native code, maximize Rails-rendered surface; sister repos `../carhey-android`, `../carhey-ios`; design parity native↔web.
+- **Project specifics** (`3-project-specifics.mdc`): mobile-first Hotwire Native hybrid; minimize native code, maximize Rails-rendered surface; sister repos `../hostapp-android`, `../hostapp-ios`; design parity native↔web.
 - **Namespacing**: domain modules as dirs — `Ride::` (`app/models/ride/*.rb`), `User::TripFeed` (`app/models/user/trip_feed.rb`), controllers under `users/`, `native/`, `ride/`, `compliance/`; jobs namespaced (`app/jobs/operations/`, `Operations::ReportAlertJob` per `config/initializers/moderate.rb:52`) on Solid Queue.
 - **Mailers**: `*Goodmailer` classes; `DeviseGoodmailer < Devise::Mailer` rebuilds every Devise email with goodmail's DSL (`text`/`button`/`code_box`/`sign`) (`app/mailers/devise_goodmailer.rb`); brand config in `config/initializers/goodmail.rb`.
 - **Testing**: Minitest, `parallelize(workers: :number_of_processors)`, `fixtures :all`, helpers `create_user`/`create_organization_for`, PostGIS SRID bootstrap (`test/test_helper.rb:8-40`).
@@ -224,26 +224,26 @@ stamped by an application-level interceptor with `.header()` replace-not-append
 
 ## LicenseSeat (second target app: plain-web RailsFast SaaS)
 
-`/Users/javi/GitHub/licenseseat` — Rails 8 licensing SaaS, same RailsFast template, **no Hotwire Native shell**, UI in English.
+`/path/to/repos/licenseseat` — Rails 8 licensing SaaS, same RailsFast template, **no Hotwire Native shell**, UI in English.
 
 - **Auth stack is the same RailsFast wiring**: identical Devise module list incl. `:trackable` (`app/models/user.rb:6-8`), identical 4 custom controllers (`config/routes.rb:2-7`), `DeviseGoodmailer`, Turnstile, madmin drawn at `/admin/dashboard` (`config/routes.rb:36-37`), `users.admin` boolean. Differences: devise **4.9.4** (`Gemfile.lock:167`) and a leaner initializer — `allow_unconfirmed_access_for = 6.hours`, **no** `remember_for`/`extend_remember_period`/`rememberable_options` overrides, **no** custom failure app (verified non-comment lines of `config/initializers/devise.rb`). So the gem must span devise 4.x and 5.x.
-- **Leaner users table**: trackable columns + `signup_ip/_city/_country/_country_code` only — none of CarHey's 18 UA/device/display `signup_*` columns, no `last_seen_*` (users table in `db/schema.rb`, cols at offsets :2-26 of the block). No `SignupAttribution`; `device_detector` not in the Gemfile.
-- **Trackdown 0.3.1 with a full initializer** (`config/initializers/trackdown.rb`): `provider = :auto`, MaxMind account/license from credentials, `db/geodata/GeoLite2-City.mmdb`, `reject_private_ips` in prod, auto-download on boot, plus `TrackdownDatabaseRefreshJob` (`app/jobs/trackdown_database_refresh_job.rb:1-5`). Same single sync call site at signup (`app/controllers/users/registrations_controller.rb:80-87`). This is the MaxMind-backed config shape the gem's soft dependency should also support (vs CarHey's zero-config CF-header mode).
+- **Leaner users table**: trackable columns + `signup_ip/_city/_country/_country_code` only — none of HostApp's 18 UA/device/display `signup_*` columns, no `last_seen_*` (users table in `db/schema.rb`, cols at offsets :2-26 of the block). No `SignupAttribution`; `device_detector` not in the Gemfile.
+- **Trackdown 0.3.1 with a full initializer** (`config/initializers/trackdown.rb`): `provider = :auto`, MaxMind account/license from credentials, `db/geodata/GeoLite2-City.mmdb`, `reject_private_ips` in prod, auto-download on boot, plus `TrackdownDatabaseRefreshJob` (`app/jobs/trackdown_database_refresh_job.rb:1-5`). Same single sync call site at signup (`app/controllers/users/registrations_controller.rb:80-87`). This is the MaxMind-backed config shape the gem's soft dependency should also support (vs HostApp's zero-config CF-header mode).
 - **`footprinted` 0.3.1 is ACTIVE** (`Gemfile:181`): `footprints` table (`db/schema.rb:119-160`) is polymorphic geo+device telemetry — `event_type`, `inet ip`, lat/lng, country/city/continent, plus promoted device columns `device_id`, `app_version`, `platform`, `os_name/_version`, `device_type`, `architecture`, `cpu_cores`, `memory_gb`, `jsonb metadata`. Configured async (`config/initializers/footprinted.rb`: `config.async = true`), metadata→column promotion monkey-patch (`config/initializers/footprinted_extensions.rb`), used for **product/licensing telemetry** (DAU/MAU by `device_id`, `app/models/concerns/product_analytics.rb:13-27`; intake via `app/controllers/concerns/license_seat_telemetry.rb`) — *not* for login tracking. It's the closest existing schema to a "device" row in either app.
 - **Token auth exists**: `api_keys` 0.3.0 (git main; `Gemfile:190`) — org-owned `pk_`/`sk_` keys with per-key permissions (`config/initializers/api_keys.rb:1-25`), `api_keys` table with `last_used_at`/`revoked_at`/`token_digest` (`db/schema.rb:45-75`), self-serve UI under `namespace :settings { resources :api_keys ... }` (`config/routes.rb:160-162`) and madmin resources at `app/madmin/resources/api_keys/`. The licensing API authenticates with these keys, not cookies — session tracking must not swallow those requests. `license_seat_activations` even stores `ip_address` per machine activation (`db/schema.rb:192-198`).
-- **Settings layout differs**: single `settings#show` (`config/routes.rb:157`) + a `settings` namespace for sub-resources; views are form partials (`app/views/settings/_account_form.html.erb`, `_organization_form.html.erb`) rather than CarHey's setting_row sections. A sessions page here would naturally be `settings/sessions` inside that namespace.
+- **Settings layout differs**: single `settings#show` (`config/routes.rb:157`) + a `settings` namespace for sub-resources; views are form partials (`app/views/settings/_account_form.html.erb`, `_organization_form.html.erb`) rather than HostApp's setting_row sections. A sessions page here would naturally be `settings/sessions` inside that namespace.
 - No `moderate`/`AuditLog` (moderate commented at `Gemfile:184`); audit needs are gem-owned (`license_seat_audit_events`, `db/schema.rb:214`).
 
 ## Implications for the sessions gem (opinion)
 
-1. **Own the truth in a DB-backed session/device registry** (à la Rails 8 `Session` model): a signed per-device cookie (or session-id claim) checked against a `sessions` row each request. That's the only way to get enumeration + revocation on top of CookieStore — and it must also bind/rotate with Devise's remember-me, since CarHey's native sessions are effectively 1-year remember cookies (`sessions_controller.rb:187-198`). Per-device remember tokens or a session-epoch column on the row is the revocation primitive.
-2. **Hook Warden, not Devise controllers**: `after_set_user`/`after_authentication`/`before_logout` covers stock + CarHey's manual native branch (which still calls `sign_in`); ship a separate adapter for Rails 8 omakase auth (no Warden there). Never run model callbacks in the hot path — see the read-only `warden.user(run_callbacks: false)` pattern and the stale-remember-cookie bootstrap (`application_controller.rb:360-417`) the gem must coexist with.
-3. **Record failures too**: subscribe to `warden.authenticate` failure / Devise lockable paths; CarHey's manual branch renders 422 without touching Warden's failure app (`sessions_controller.rb:96-118`), so the gem needs an explicit `track_failed_attempt` seam callable from custom controllers.
+1. **Own the truth in a DB-backed session/device registry** (à la Rails 8 `Session` model): a signed per-device cookie (or session-id claim) checked against a `sessions` row each request. That's the only way to get enumeration + revocation on top of CookieStore — and it must also bind/rotate with Devise's remember-me, since HostApp's native sessions are effectively 1-year remember cookies (`sessions_controller.rb:187-198`). Per-device remember tokens or a session-epoch column on the row is the revocation primitive.
+2. **Hook Warden, not Devise controllers**: `after_set_user`/`after_authentication`/`before_logout` covers stock + HostApp's manual native branch (which still calls `sign_in`); ship a separate adapter for Rails 8 omakase auth (no Warden there). Never run model callbacks in the hot path — see the read-only `warden.user(run_callbacks: false)` pattern and the stale-remember-cookie bootstrap (`application_controller.rb:360-417`) the gem must coexist with.
+3. **Record failures too**: subscribe to `warden.authenticate` failure / Devise lockable paths; HostApp's manual branch renders 422 without touching Warden's failure app (`sessions_controller.rb:96-118`), so the gem needs an explicit `track_failed_attempt` seam callable from custom controllers.
 4. **Adopt the AuditLog.log signature** (`event_type:, data:, user:, request:`) for its event API and `inet ip_address` + `text user_agent` column types; offer an optional sink so apps can tee login events into their own AuditLog.
-5. **Lift SignupAttribution into the gem as the per-session parser** (device_detector + Client Hints + Hotwire Native tokens incl. configurable app-prefix regexes like `CarHey Android`, plus `bridge-components:` parsing) and honor `X-Client-Platform/Version/Build/OS` with `ClientVersionInfo`-style validation. That turns CarHey's signup-only intelligence into every-session intelligence and lets the gem name devices "CarHey en Pixel 7 (Android 14)".
+5. **Lift SignupAttribution into the gem as the per-session parser** (device_detector + Client Hints + Hotwire Native tokens incl. configurable app-prefix regexes like `HostApp Android`, plus `bridge-components:` parsing) and honor `X-Client-Platform/Version/Build/OS` with `ClientVersionInfo`-style validation. That turns HostApp's signup-only intelligence into every-session intelligence and lets the gem name devices "HostApp en Pixel 7 (Android 14)".
 6. **Copy the throttled `update_all ... IS DISTINCT FROM` touch** (`api/v1/base_controller.rb:32-57`) for per-session `last_seen_at` — hot-row safe, callback-free.
-7. **Geo = trackdown soft dependency, both modes**: sync CF-header path when free (CarHey), async job fallback for MaxMind lookups (LicenseSeat shape); never block sign-in on geo (mirror the rescue at `registrations_controller.rb:45-53`).
-8. **UI**: ship a controller + plain-Tailwind views/partials apps can render inside their own settings shell (CarHey's `setting_row` sections vs LicenseSeat's `settings` namespace prove one fixed page won't fit); i18n-first (CarHey is Spanish). Provide a madmin resource template mirroring `audit_log_resource.rb`. New-device email should be a plain ActionMailer that apps can override with a `*Goodmailer`.
+7. **Geo = trackdown soft dependency, both modes**: sync CF-header path when free (HostApp), async job fallback for MaxMind lookups (LicenseSeat shape); never block sign-in on geo (mirror the rescue at `registrations_controller.rb:45-53`).
+8. **UI**: ship a controller + plain-Tailwind views/partials apps can render inside their own settings shell (HostApp's `setting_row` sections vs LicenseSeat's `settings` namespace prove one fixed page won't fit); i18n-first (HostApp is Spanish). Provide a madmin resource template mirroring `audit_log_resource.rb`. New-device email should be a plain ActionMailer that apps can override with a `*Goodmailer`.
 9. **Stay out of token-auth lanes**: skip tracking for `api_keys`-authenticated and other non-cookie requests by default (LicenseSeat's licensing API).
 10. **Schema suggestion**: `sessions` (per device/browser: user, token/epoch, ip `inet`, ua `text`, parsed client/platform/browser/os/app_version/app_build/device_model, geo country/city, created/last_seen/revoked_at, revoked_reason) + `login_attempts` (success+failure, email-as-typed, user nullable, ip, ua, geo, failure_reason) — append-only like AuditLog but without the hash chain in v1 (advisory-lock serialization is explicitly unsuitable for high-frequency writes per `audit_log.rb` comments echoed in `api/v1/base_controller.rb:29-30`). Use UUID PKs — every table in both apps is `id: :uuid, default: gen_random_uuid()` — but don't hard-require Postgres types if SQLite support matters. Leave a `push_token` column or a `session_devices`-style association point for the push registration neither app has yet.
 

data/docs/research/02-ecosystem.md

@@ -3,7 +3,7 @@
 Research memo for the `sessions` gem (drop-in session & login-activity tracking, device management, Rails 8+).
 Sources: read-only study of 10 local repos — `trackdown`, `footprinted` (deep dives), `usage_credits`,
 `pricing_plans`, `api_keys`, `nondisposable`, `profitable`, `wallets` (mature, trust most), `moderate`, `chats`
-(newer, best for UI-shipping + host hooks). All 10 repos present. Citations are `path:line` under `/Users/javi/GitHub/`.
+(newer, best for UI-shipping + host hooks). All 10 repos present. Citations are `path:line` under `/path/to/repos/`.
 
 ## Top findings
 

data/docs/research/07-device-detection.md

@@ -1,6 +1,6 @@
 # Device intelligence: UA parsing, Hotwire Native, client hints, IP capture
 
-Researched 2026-06-11. Code citations are from read-only clones under `/tmp/sessions-research/` (browser, device_detector, hotwire-native-ios, hotwire-native-android, turbo-rails, rails-stable @ v8.1.3) and the local apps under `/Users/javi/GitHub/`. Web citations carry URL + fetch date.
+Researched 2026-06-11. Code citations are from read-only clones under `/tmp/sessions-research/` (browser, device_detector, hotwire-native-ios, hotwire-native-android, turbo-rails, rails-stable @ v8.1.3) and the local apps under `/path/to/repos/`. Web citations carry URL + fetch date.
 
 ## Top findings
 
@@ -11,7 +11,7 @@ Researched 2026-06-11. Code citations are from read-only clones under `/tmp/sess
 - **Android WebView is explicitly excluded from Chrome's UA reduction** ("We don't have current plans for User-Agent Reduction on iOS and Android WebView" — chromium.org/updates/ua-reduction, fetched 2026-06-10). So Hotwire Native **Android** UAs still carry real device model + real Android version. Hotwire Native **iOS** UAs carry real iOS version but never the hardware model.
 - **Web Chrome UAs are husks since 2023**: frozen `Windows NT 10.0`, `Intel Mac OS X 10_15_7`, `Linux; Android 10; K`, minor versions `0.0.0`. Real data moved to UA Client Hints — which **only Chromium ships; Safari and Firefox still refuse as of June 2026**.
 - **iPadOS masquerades as macOS by default** since iPadOS 13 — server-side, an iPad on Safari is byte-identical to a Mac. No fix without JS.
-- **Our four local apps customize the UA prefix today but none embeds app version or (iOS) device model** — the gem should ship a recommended prefix convention; CarHey's native HTTP client already proves the pattern (`"CarHey Android 1.0.5 (build 6; Android 14; sdk 34; Pixel 7)"`).
+- **Our four local apps customize the UA prefix today but none embeds app version or (iOS) device model** — the gem should ship a recommended prefix convention; HostApp's native HTTP client already proves the pattern (`"HostApp Android 1.0.5 (build 6; Android 14; sdk 34; Pixel 7)"`).
 - **`request.remote_ip` behind Cloudflare returns a Cloudflare edge IP** unless CF ranges are added to `trusted_proxies` (which *replaces* the private-range defaults) — document `cloudflare-rails` or an `ip_resolver` hook. Portable IP column: `string limit: 45`; `inet` is Postgres-only.
 
 ## A. Ruby UA parsers: `browser` vs `device_detector`
@@ -56,7 +56,7 @@ Researched 2026-06-11. Code citations are from read-only clones under `/tmp/sess
 1. **Always persist the raw UA in a `text` column** (no 255 limit) plus the relevant raw Client-Hint headers when present. Parsing is a *projection* that can be re-run as parsers/conventions improve. Validated by uniform prior art.
 2. **Hard dependency on `browser`** as the default web parser: MIT, zero-dep, tiny, Rails-aware, good enough for "Chrome 137 on macOS" + bot flagging. A drop-in gem needs device intel working with zero setup; an adapter-only design would gut the first-run experience.
 3. **Optional `device_detector` adapter** (auto-upgrade if the host app bundles it): better device names on legacy/Android UAs, native Client-Hints handling, much bigger bot DB. Don't hard-depend: LGPL, 1.5 MB data, 2-years-stale releases.
-4. **Built-in native-app UA parser that runs first** (before any web parser): recognizes `Hotwire Native iOS|Android`, `Turbo Native`, the recommended prefix convention below, and CarHey's existing shapes. This is the gem's actual moat; no third-party parser does it.
+4. **Built-in native-app UA parser that runs first** (before any web parser): recognizes `Hotwire Native iOS|Android`, `Turbo Native`, the recommended prefix convention below, and HostApp's existing shapes. This is the gem's actual moat; no third-party parser does it.
 5. Expose `config.ua_parser = :browser | :device_detector | ->(ua, headers) { DeviceInfo.new(...) }` for escape hatches, and stamp rows with parser identity/version if cheap (optional).
 
 ## B. Hotwire Native user agents
@@ -125,17 +125,17 @@ Substring contract: `"Turbo Native"` or `"Hotwire Native"` anywhere in the UA. T
 
 | App | Prefix set | Where | Effective UA shape |
 |---|---|---|---|
-| carhey-ios | `"CarHey iOS; RailsFast Native iOS;"` (`{App}` from `CFBundleDisplayName`) | `RailsFast/Core/AppConfiguration.swift:10-12`, applied `RailsFast/App/AppDelegate.swift:103` | `Mozilla/5.0 (iPhone; CPU iPhone OS x_y like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CarHey iOS; RailsFast Native iOS; Hotwire Native iOS; Turbo Native iOS; bridge-components: […]` |
+| hostapp-ios | `"HostApp iOS; RailsFast Native iOS;"` (`{App}` from `CFBundleDisplayName`) | `RailsFast/Core/AppConfiguration.swift:10-12`, applied `RailsFast/App/AppDelegate.swift:103` | `Mozilla/5.0 (iPhone; CPU iPhone OS x_y like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) HostApp iOS; RailsFast Native iOS; Hotwire Native iOS; Turbo Native iOS; bridge-components: […]` |
 | railsfast-ios | `"RailsFast iOS; RailsFast Native iOS;"` | `RailsFast/Core/AppConfiguration.swift:10-12`, `RailsFast/App/AppDelegate.swift:93-99` | same shape, `RailsFast` tokens |
-| carhey-android | `"CarHey Android;"` | `app/src/main/java/com/carhey/android/CarHeyApplication.kt:169` | `CarHey Android; Hotwire Native Android; Turbo Native Android; bridge-components: […]; Mozilla/5.0 (Linux; Android NN; <Model> Build/…; wv) … Chrome/NNN.0.0.0 Mobile Safari/537.36` |
+| hostapp-android | `"HostApp Android;"` | `app/src/main/java/com/hostapp/android/HostAppApplication.kt:169` | `HostApp Android; Hotwire Native Android; Turbo Native Android; bridge-components: […]; Mozilla/5.0 (Linux; Android NN; <Model> Build/…; wv) … Chrome/NNN.0.0.0 Mobile Safari/537.36` |
 | railsfast-android | `"${BuildConfig.APPLICATION_NAME} Android; RailsFast Native Android;"` | `app/src/main/java/com/railsfast/android/RailsFastApplication.kt:45-46` | same shape with two leading brand segments |
 
 So today: **no webview UA carries the app version anywhere, and iOS UAs carry no device model.** Android model/OS arrive free via the WebView default UA.
 
-However, CarHey's *native* (URLSession/OkHttp) calls already use a richer convention the gem should accept as prior art:
+However, HostApp's *native* (URLSession/OkHttp) calls already use a richer convention the gem should accept as prior art:
 
-- iOS: `"\(applicationName) iOS \(version) (build \(build); iOS \(osVersion); \(resolvedModel))"` → e.g. `CarHey iOS 1.0.5 (build 6; iOS 19.5; iPhone15,2)` (`carhey-ios/RailsFast/Core/NativeHttpClient.swift:61-71`), plus headers `X-Client-Platform/-Version/-Build/-OS` (`NativeHttpClient.swift:13-17`).
-- Android: `"CarHey Android $versionName (build $versionCode; Android $osRelease; sdk $sdkInt; $device)"` → e.g. `CarHey Android 1.0.5 (build 6; Android 14; sdk 34; Pixel 7)` (`carhey-android/app/src/main/java/com/carhey/android/ClientHeaders.kt:66-76`; header names `:25-29`).
+- iOS: `"\(applicationName) iOS \(version) (build \(build); iOS \(osVersion); \(resolvedModel))"` → e.g. `HostApp iOS 1.0.5 (build 6; iOS 19.5; iPhone15,2)` (`hostapp-ios/RailsFast/Core/NativeHttpClient.swift:61-71`), plus headers `X-Client-Platform/-Version/-Build/-OS` (`NativeHttpClient.swift:13-17`).
+- Android: `"HostApp Android $versionName (build $versionCode; Android $osRelease; sdk $sdkInt; $device)"` → e.g. `HostApp Android 1.0.5 (build 6; Android 14; sdk 34; Pixel 7)` (`hostapp-android/app/src/main/java/com/hostapp/android/ClientHeaders.kt:66-76`; header names `:25-29`).
 
 ### Recommended UA convention for the gem's README
 
@@ -143,11 +143,11 @@ Use an RFC 9110-style product token as the `applicationUserAgentPrefix`, ending
 
 ```text
 <AppName>/<version> (<model>; <os> <os_version>; build <build>);
-e.g.  CarHey/2.4.1 (iPhone15,2; iOS 19.5; build 241);
-e.g.  CarHey/2.4.1 (Pixel 8; Android 16; build 241);
+e.g.  HostApp/2.4.1 (iPhone15,2; iOS 19.5; build 241);
+e.g.  HostApp/2.4.1 (Pixel 8; Android 16; build 241);
 ```
 
-Parse rule (gem-side, tolerant): `%r{(?<app>[\w .-]+)/(?<version>\d[\w.]*) \((?<fields>[^)]*)\)}` with semicolon-split, order-insensitive fields; also accept CarHey's space-separated legacy `"CarHey iOS 1.0.5 (build 6; …)"`. Everything else (Hotwire markers, WebView UA) stays intact, so `hotwire_native_app?` and bridge components keep working.
+Parse rule (gem-side, tolerant): `%r{(?<app>[\w .-]+)/(?<version>\d[\w.]*) \((?<fields>[^)]*)\)}` with semicolon-split, order-insensitive fields; also accept HostApp's space-separated legacy `"HostApp iOS 1.0.5 (build 6; …)"`. Everything else (Hotwire markers, WebView UA) stays intact, so `hotwire_native_app?` and bridge components keep working.
 
 README client snippets:
 
@@ -156,7 +156,7 @@ README client snippets:
 ```swift
 var u = utsname(); uname(&u)
 let model = withUnsafeBytes(of: &u.machine) { String(decoding: $0.prefix(while: { $0 != 0 }), as: UTF8.self) }
-Hotwire.config.applicationUserAgentPrefix = "CarHey/\(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0") (\(model); iOS \(UIDevice.current.systemVersion));"
+Hotwire.config.applicationUserAgentPrefix = "HostApp/\(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "0") (\(model); iOS \(UIDevice.current.systemVersion));"
 ```
 
 (`model` is `"iPhone15,2"` on device, `"arm64"` on Simulator — fine for production traffic.)
@@ -165,7 +165,7 @@ Hotwire.config.applicationUserAgentPrefix = "CarHey/\(Bundle.main.infoDictionary
 
 ```kotlin
 Hotwire.config.applicationUserAgentPrefix =
-    "CarHey/${BuildConfig.VERSION_NAME} " +
+    "HostApp/${BuildConfig.VERSION_NAME} " +
     "(${Build.MODEL}; Android ${Build.VERSION.RELEASE}; build ${BuildConfig.VERSION_CODE});"
 ```
 

data/lib/generators/sessions/install_generator.rb

@@ -181,7 +181,7 @@ module Sessions
         say "           schedule: every day at 4am"
 
         say "\nEvery login now lands on the devices page and in the trail:"
-        say "  current_user.sessions.active     # live devices, revocable"
+        say "  current_user.sessions.live       # live devices, revocable"
         say "  current_user.session_history     # the trail — logins, failures, revocations"
         say "\nEvery session, every device, every login — tracked. 🔐✨\n", :green
       end

data/lib/generators/sessions/madmin_generator.rb

@@ -28,7 +28,7 @@ module Sessions
 
           This generator produces Madmin resources for the session registry and
           the login trail. For other admin frameworks, build on the same
-          primitives it uses: Session.active / session.revoke! /
+          primitives it uses: Session.live / session.revoke! /
           Sessions::Event scopes (failed_logins, last_24_hours, …).
         MSG
       end
@@ -71,12 +71,12 @@ module Sessions
 
         say "\n  3. (Optional) For a per-user panel (devices + trail on the user's"
         say "     show page), add a member action to your users controller that"
-        say "     loads `user.sessions.by_recency` and `user.session_history.recent`"
+        say "     loads `user.sessions.live.by_recency` and `user.session_history.recent`"
         say "     — the README's Admin section has the full recipe."
 
-        say "\nRevoking from the index destroys the row: that device is signed out"
-        say "on its very next request, and the revocation lands in the trail with"
-        say "admin attribution. 🔐\n", :green
+        say "\nRevoking from the index ends the row in place: that device is signed out"
+        say "on its very next matching request, and the revocation lands in the trail"
+        say "with admin attribution. 🔐\n", :green
       end
 
       private

data/lib/generators/sessions/templates/add_lifecycle_to_sessions.rb.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# v0.2 upgrade: session rows are lifecycle records now. A live device is
+# `ended_at: nil`; explicit ending state lives on the row instead of being
+# inferred from a missing row plus a sessions_events tombstone.
+class AddSessionsLifecycleTo<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    change_table :<%= table_name %>, bulk: true do |t|
+      t.datetime :ended_at unless column_exists?(:<%= table_name %>, :ended_at)
+      t.string :ended_reason unless column_exists?(:<%= table_name %>, :ended_reason)
+      t.string :ended_by_type unless column_exists?(:<%= table_name %>, :ended_by_type)
+      t.send(reference_column_type, :ended_by_id) unless column_exists?(:<%= table_name %>, :ended_by_id)
+      t.send(json_column_type, :ended_metadata) unless column_exists?(:<%= table_name %>, :ended_metadata)
+    end
+
+    add_index :<%= table_name %>, :ended_at unless index_exists?(:<%= table_name %>, :ended_at)
+    add_index :<%= table_name %>, :ended_reason unless index_exists?(:<%= table_name %>, :ended_reason)
+    add_index :<%= table_name %>, %i[ended_by_type ended_by_id] unless index_exists?(:<%= table_name %>, %i[ended_by_type ended_by_id])
+  end
+
+  private
+
+  def reference_column_type
+    config = Rails.configuration.generators
+    case config.options[config.orm][:primary_key_type]
+    when :uuid then :uuid
+    when :string then :string
+    when :integer, :serial then :integer
+    else :bigint
+    end
+  end
+
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/postg/i)
+
+    :json
+  end
+end

data/lib/generators/sessions/templates/add_sessions_columns.rb.erb

@@ -64,6 +64,14 @@ class AddSessionsColumnsTo<%= table_name.camelize %> < ActiveRecord::Migration<%
       # Session.sweep recommendation always needed.
       t.datetime :last_seen_at
       t.string :last_seen_ip, limit: 45 # refreshed with the touch (roaming devices)
+
+      # Lifecycle state. `ended_at: nil` is the live-device set; ended rows
+      # remain as auditable history. Events are the trail, not the source of
+      # truth for whether a session should still be accepted.
+      t.datetime :ended_at
+      t.string :ended_reason
+      t.references :ended_by, polymorphic: true, type: foreign_key_type
+      t.send(json_column_type, :ended_metadata)
     end
 
     add_index :<%= table_name %>, :device_id
@@ -73,10 +81,28 @@ class AddSessionsColumnsTo<%= table_name.camelize %> < ActiveRecord::Migration<%
     add_index :<%= table_name %>, :auth_provider
     add_index :<%= table_name %>, :country_code
     add_index :<%= table_name %>, :last_seen_at
+    add_index :<%= table_name %>, :ended_at
+    add_index :<%= table_name %>, :ended_reason
+    add_index :<%= table_name %>, %i[ended_by_type ended_by_id]
   end
 
   private
 
+  def foreign_key_type
+    config = Rails.configuration.generators
+    reference_column_type(config.options[config.orm][:primary_key_type])
+  end
+
+  # Reference columns hold VALUES of the PK type, so serial pseudo-types map to
+  # their plain integer equivalents.
+  def reference_column_type(setting)
+    case setting
+    when nil, :bigserial then :bigint
+    when :serial then :integer
+    else setting
+    end
+  end
+
   # :jsonb on PostgreSQL, :json elsewhere — same adaptive pattern as the
   # rest of the gem ecosystem (chats, api_keys, …). match? (not equality):
   # PostGIS apps report adapter_name "PostGIS" and are PostgreSQL too.

data/lib/generators/sessions/templates/create_sessions.rb.erb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-# The Rails-8-shaped sessions table for a Devise app: one row = one
-# signed-in device, destroyed on logout/revocation (rows = active sessions;
-# history lives in sessions_events). Deliberately the SAME base shape
+# The Rails-8-shaped sessions table for a Devise app: one row = one signed-in
+# device lifecycle (`ended_at: nil` means live; history lives in
+# sessions_events). Deliberately the SAME base shape
 # `rails generate authentication` creates — so if you ever migrate from
 # Devise to Rails auth, your sessions table is already waiting.
 class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_version %>
@@ -23,8 +23,8 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
 
       # Devise/Warden mode: SHA-256 of a random token whose raw value lives
       # ONLY in the user's own session (OWASP: never persist raw session
-      # identifiers). The Warden adapter validates it on every request —
-      # destroy the row and that device is signed out on its next request.
+      # identifiers). The Warden adapter validates it on every request; only
+      # a matching token plus explicit lifecycle end may sign that device out.
       t.string :token_digest
 
       # The Warden scope ("user") — multi-scope Devise apps.
@@ -72,6 +72,15 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
       t.datetime :last_seen_at
       t.string :last_seen_ip, limit: 45
 
+      # Lifecycle state. v0.2 keeps rows as the source of truth instead of
+      # deleting them and asking events to act as tombstones. `ended_at: nil`
+      # is the live-device set; explicit ended_reason values are the only
+      # thing a Devise/Warden request is allowed to enforce.
+      t.datetime :ended_at
+      t.string :ended_reason
+      t.references :ended_by, polymorphic: true, type: foreign_key_type
+      t.send(json_column_type, :ended_metadata)
+
       t.timestamps
     end
 
@@ -82,6 +91,9 @@ class Create<%= table_name.camelize %> < ActiveRecord::Migration<%= migration_ve
     add_index :<%= table_name %>, :auth_provider
     add_index :<%= table_name %>, :country_code
     add_index :<%= table_name %>, :last_seen_at
+    add_index :<%= table_name %>, :ended_at
+    add_index :<%= table_name %>, :ended_reason
+    add_index :<%= table_name %>, %i[ended_by_type ended_by_id]
   end
 
   private

data/lib/generators/sessions/templates/create_sessions_events.rb.erb

@@ -23,10 +23,10 @@ class CreateSessionsEvents < ActiveRecord::Migration<%= migration_version %>
       t.references :authenticatable, polymorphic: true, type: foreign_key_type, index: false
       t.string :scope
 
-      # The trail ↔ registry linkage. A plain column, NO foreign key: the
-      # registry row it points at gets destroyed on revoke; history must
-      # survive. A suspicious login here is one lookup away from revoking
-      # the live session it created.
+      # The trail ↔ registry linkage. A plain column, NO foreign key:
+      # lifecycle rows are normally ended in place, but account-erasure and
+      # legacy host deletes may still remove them. A suspicious login here
+      # is one lookup away from revoking the live session it created.
       t.send(session_id_column_type, :session_id)
 
       t.string :identity # email-as-typed (normalized), even for unknown accounts

data/lib/generators/sessions/templates/initializer.rb

@@ -122,8 +122,8 @@ Sessions.configure do |config|
   # "Was this you?" email here. Not fired on a user's very first login.
   #
   # PASS THE EVENT to your mailer, not the session: the event is a
-  # persisted, GlobalID-able record that survives revocation (the session
-  # row may be destroyed before an async job runs) and already carries
+  # persisted, GlobalID-able record that survives revocation and account
+  # erasure cleanup, and already carries
   # everything the email needs — event.user, event.device_name,
   # event.location, event.country_flag, event.occurred_at.
   #

data/lib/generators/sessions/templates/madmin/session_resource.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-# Live device registry (sessions gem): one row = one signed-in device,
-# destroyed on logout/revocation — so this index IS the set of sessions that
-# can act on your app right now. The append-only history lives in
-# Sessions::Event (see Sessions::EventResource).
+# Device lifecycle registry (sessions gem): one row = one signed-in device.
+# `ended_at: nil` is the live set that can act on your app right now; ended
+# rows stay around as durable state/audit context until retention or account
+# erasure removes them. The append-only history lives in Sessions::Event.
 class SessionResource < Madmin::Resource
   model <%= session_class %>
 
@@ -30,6 +30,8 @@ class SessionResource < Madmin::Resource
   attribute :app_build, index: false, form: false
   attribute :user_agent, index: false, form: false
   attribute :last_seen_at, index: true, form: false, label: "Last seen"
+  attribute :ended_at, index: true, form: false, label: "Ended"
+  attribute :ended_reason, index: true, form: false, label: "Ended because"
   attribute :created_at, index: true, form: false, label: "Signed in"
   attribute :updated_at, show: false, form: false
 
@@ -39,8 +41,14 @@ class SessionResource < Madmin::Resource
   attribute :adoption_key, show: false, form: false
   attribute :auth_detail, show: false, form: false
   attribute :client_hints, show: false, form: false
+  attribute :ended_by_type, show: false, form: false
+  attribute :ended_by_id, show: false, form: false
+  attribute :ended_metadata, show: false, form: false
 
-  # Gem scopes: active = last activity within 30 days.
+  # Gem scopes: live/ended are lifecycle state; active/inactive are UI
+  # grouping within the live set (last activity within 30 days).
+  scope :live
+  scope :ended
   scope :active
   scope :inactive
 
@@ -53,9 +61,9 @@ class SessionResource < Madmin::Resource
   def self.default_sort_column = "created_at"
   def self.default_sort_direction = "desc"
 
-  # Remote logout: destroys the row (the device is signed out on its next
-  # request), writes the `revoked` trail event attributed to the admin, and
-  # rotates the user's remember-me credentials in Devise mode.
+  # Remote logout: ends the row in place, writes the `revoked` trail event
+  # attributed to the admin, and rotates the user's remember-me credentials
+  # in Devise mode. The device is signed out on its next matching request.
   member_action do
     button_to "Revoke session",
       main_app.revoke_madmin_session_path(@record),

data/lib/generators/sessions/templates/madmin/sessions_controller.rb

@@ -2,10 +2,10 @@
 
 module Madmin
   class SessionsController < Madmin::ResourceController
-    # Admin remote logout. `revoke!` destroys the row (the device is kicked
-    # on its next request — the cookie session and, in Devise mode, any
-    # remember-me revival), and writes the immutable `revoked` trail event
-    # with `by:` attribution.
+    # Admin remote logout. `revoke!` ends the row in place (the device is
+    # kicked on its next matching request — the cookie session and, in Devise
+    # mode, any remember-me revival), and writes the immutable `revoked`
+    # trail event with `by:` attribution.
     def revoke
       session_row = <%= session_class %>.find(params[:id])
       device = session_row.device_name

data/lib/generators/sessions/upgrade_generator.rb

@@ -27,6 +27,8 @@ module Sessions
                            File.join(db_migrate_path, "add_sessions_adoption_key_to_#{table_name}.rb")
         migration_template "add_app_build_to_sessions_events.rb.erb",
                            File.join(db_migrate_path, "add_sessions_app_build_to_sessions_events.rb")
+        migration_template "add_lifecycle_to_sessions.rb.erb",
+                           File.join(db_migrate_path, "add_sessions_lifecycle_to_#{table_name}.rb")
       end
 
       def display_post_upgrade_message
@@ -34,7 +36,8 @@ module Sessions
         say "\nTo complete the upgrade:"
         say "  1. Review the generated migration."
         say "  2. Run 'rails db:migrate'."
-        say "     ⚠️  Deploy the migrations before relying on adoption hardening or app-build event columns.", :yellow
+        say "     ⚠️  Deploy the migrations before relying on lifecycle-row revocation, " \
+            "adoption hardening, or app-build event columns.", :yellow
       end
 
       private