studio-engine 0.30.0 → 0.32.0

data/app/controllers/studio/links_controller.rb

@@ -1,6 +1,6 @@
 module Studio
-  # The unified short-token link entry point — GET/POST /l/<token>. Dispatches by
-  # Studio::Link#kind:
+  # The short-token link entry point — GET/POST /l/<token>, the only magic-link
+  # door the engine draws. Dispatches by Studio::Link#kind:
   #
   #   magic_link → scanner-safe confirm interstitial (GET, inert) that auto-POSTs
   #                to #consume, the ONLY place the single-use token is burned +
@@ -9,6 +9,10 @@ module Studio
   #                the link's target (or root). Reusable + safe to prefetch, so
   #                GET does the work (no POST step).
   #
+  # Every decision about what a magic-link click DOES lives in
+  # Studio::LinkConsumption / Studio::LinkResolution, not here — including the
+  # invariant that a dead link leaves the visitor's session untouched.
+  #
   # Namespaced (not top-level Links) because mcritchie-studio already owns a
   # public /links linktree (top-level LinksController). Apps needing richer
   # post-consume routing (contest landing, picks rehydration, age-gate) define
@@ -25,30 +29,24 @@ module Studio
       response.set_header("Referrer-Policy", "strict-origin")
       @link = Studio::Link.find_by(token: params[:token])
 
-      case @link&.kind
-      when "magic_link"
-        @token = params[:token]
-        render :confirm
-      when "referral"
+      if @link&.kind == "referral"
         capture_referral(@link)
-        redirect_to(@link.target || root_path)
-      else
-        redirect_to login_path, alert: "That link is invalid or has expired. Request a fresh one below."
+        return redirect_to(@link.target || root_path)
       end
+
+      # A magic link, or a token with no row behind it. preview_magic_link is
+      # inert — it never burns — and settles a dead link itself rather than
+      # sending the visitor through a spinner that only POSTs to learn the same.
+      @token = params[:token]
+      render :confirm if preview_magic_link(@link&.kind == "magic_link" ? @link : nil) == :live
     end
 
     # POST /l/:token — authoritative magic-link consume. Only magic_link kinds are
-    # consumable here; referral links are reusable and handled entirely on GET.
+    # consumable here; referral links are reusable and handled entirely on GET,
+    # so a referral token scoped out below reads as an unknown token.
     def consume
       response.set_header("Referrer-Policy", "strict-origin")
-      link = Studio::Link.find_by(token: params[:token])
-      raise Studio::Link::InvalidToken, "not a magic link" unless link&.kind == "magic_link"
-
-      link.consume! # burns the single-use token; raises if already used / expired
-      user = User.find_by(email: link.email)
-      user ? sign_in_existing(user, link) : sign_up_new(link)
-    rescue Studio::Link::InvalidToken
-      redirect_to login_path, alert: "That sign-in link is invalid or has expired. Request a fresh one below."
+      consume_magic_link(Studio::Link.magic_links.find_by(token: params[:token]))
     end
 
     private

data/app/controllers/studio/local_reviews_controller.rb

@@ -30,10 +30,10 @@ module Studio
       email = Studio::LinkToken.normalize_email(params[:email])
       return redirect_to(login_path, alert: MISSING_EMAIL) unless email.match?(URI::MailTo::EMAIL_REGEXP)
 
-      # return_to is passed through raw: BOTH stores sanitize it to a same-origin
-      # path on the way in (Studio::Link.create_magic_link and MagicLink.generate
-      # each call Studio::LinkToken.sanitize_path). Re-sanitizing here would be a
-      # second spelling of a rule that already has one owner — and a mutation run
+      # return_to is passed through raw: the store sanitizes it to a same-origin
+      # path on the way in (Studio::Link.create_magic_link calls
+      # Studio::LinkToken.sanitize_path). Re-sanitizing here would be a second
+      # spelling of a rule that already has one owner — and a mutation run
       # confirmed it guards nothing the store does not already guard.
       token = issue_magic_link(email, params[:return_to])
       redirect_to magic_link_url_for(token), allow_other_host: false

data/app/mailers/user_mailer.rb

@@ -1,8 +1,7 @@
 class UserMailer < ApplicationMailer
-  # magic_link_url_for — the URL that consumes the token, matched to
-  # Studio.magic_link_store. Shared with the issuers that MINT the token
-  # (MagicLinksController, Studio::LocalReviewsController) so the two halves
-  # cannot drift apart.
+  # magic_link_url_for — the URL that consumes the token. Shared with the
+  # issuers that MINT it (MagicLinksController, RegistrationsController,
+  # Studio::LocalReviewsController) so the two halves cannot drift apart.
   include Studio::MagicLinkIssuing
 
   # Branded shell (banner + card) for engine-sent UserMailer emails. An app with
@@ -10,9 +9,11 @@ class UserMailer < ApplicationMailer
   layout "branded_mailer"
 
   # Passwordless sign-in link. `email` is a raw string (the recipient may not
-  # have an account yet). Token is a signed MagicLink payload (email + return_to
-  # + jti, single-use). Clicking the link logs the recipient in or creates their
-  # account. App-name-aware so the same template serves every Studio app.
+  # have an account yet). The token is a Studio::Link row's short token — 16
+  # URL-safe characters, single-use, expiring — and the email + return_to it
+  # stands for stay in the row, off the wire. Clicking the link logs the
+  # recipient in or creates their account. App-name-aware so the same template
+  # serves every Studio app.
   #
   # Engine GENERIC base. An app needing richer copy (e.g. turf-monster's
   # contest-aware variant) defines its own UserMailer, which wins.

data/app/models/studio/link.rb

@@ -11,13 +11,20 @@ module Studio
   # discriminator. Replaces the engine's stateless MessageVerifier MagicLink
   # service for mcritchie-studio so both apps share one short-token scheme.
   #
-  # Like Studio::EmailDelivery, the table lives in each consumer app (copy the
-  # reference migration in db/migrate); this model is shipped by the gem.
+  # Like Studio::EmailDelivery, the table lives in each consumer app — installed
+  # by `bin/rails studio_engine:install:migrations`, never hand-copied (a hand
+  # copy collides with the task's own copy on `class CreateStudioLinks`). This
+  # model is shipped by the gem.
   class Link < ApplicationRecord
     self.table_name = "studio_links"
 
     class InvalidToken < StandardError; end
 
+    # The app enabled :magic_link but never installed the table. Raised in place
+    # of a bare PG::UndefinedTable so the first person to hit it reads the fix
+    # instead of an adapter error — see mint!.
+    class MissingTable < StandardError; end
+
     belongs_to :linkable, polymorphic: true, optional: true
 
     validates :kind, inclusion: { in: Studio::LinkToken::KINDS }
@@ -76,6 +83,16 @@ module Studio
 
       # create! with a fresh random token, retrying the (astronomically rare)
       # unique-index collision a couple of times before surfacing the error.
+      #
+      # The MissingTable rescue exists because every consumer pins the engine as
+      # `~> 0.x`, which admits any release below 1.0 — so an app that never
+      # installed this table picks up the row store on its next `bundle update`
+      # whether or not anyone adopted it deliberately. Its boot is fine (nothing
+      # touches the table until someone signs in), and the failure then lands as
+      # a bare PG::UndefinedTable on a real person's sign-in. Naming the fix
+      # there is the difference between a five-minute repair and an outage
+      # nobody can read. The check is `table_exists?`, not a message match, so
+      # it holds on any adapter and never swallows an unrelated failure.
       def mint!(attrs)
         3.times do
           return create!(attrs.merge(token: Studio::LinkToken.generate))
@@ -83,6 +100,14 @@ module Studio
           next
         end
         create!(attrs.merge(token: Studio::LinkToken.generate))
+      rescue ActiveRecord::StatementInvalid
+        raise if table_exists?
+
+        raise MissingTable,
+              "studio-engine magic links need the studio_links table, and #{Studio.app_name} has no " \
+              "such table. Run `bin/rails studio_engine:install:migrations && bin/rails db:migrate` " \
+              "(install ALL of them). Do not hand-copy the migration — it collides with the task's " \
+              "own copy on `class CreateStudioLinks`."
       end
     end
 
@@ -106,6 +131,34 @@ module Studio
       self
     end
 
+    # The non-raising sibling of #consume!, and the one the click flow uses.
+    # Returns whether THIS caller won the burn — false for a link that was
+    # already used, has expired, or lost the atomic race to a concurrent click.
+    #
+    # Why a boolean and not the exception: "the link was dead" is not an error
+    # here, it is one of the two normal outcomes, and the branch it feeds
+    # (Studio::LinkResolution) needs the answer as data. Reloads on a loss so
+    # the caller reads the row's settled state (consumed_at / expires_at) rather
+    # than the copy it held before the race.
+    def burn
+      consume!
+      true
+    rescue InvalidToken
+      reload
+      false
+    end
+
+    # How a failed burn should be described. Only meaningful once #burn has
+    # returned false (or on a link that was never burned at all).
+    def dead_status
+      return :used if single_use? && consumed?
+      return :expired if expired?
+
+      # Neither flag is set but the burn did not land: a concurrent click won
+      # it between our read and our write. Same story for the reader.
+      :used
+    end
+
     def single_use?
       Studio::LinkToken.single_use?(kind)
     end

data/app/views/studio/_confirm_interstitial.html.erb

@@ -1,9 +1,10 @@
 <%#
   Shared scanner-safe sign-in interstitial. The GET that renders this is inert;
   the page auto-POSTs the CSRF-protected form to `consume_path` (the only place
-  a single-use token is burned). Used by both MagicLinksController#confirm
-  (consume_path: magic_link_consume_path) and Studio::LinksController#show
-  (consume_path: link_consume_path). Rendered with layout false (full document).
+  a single-use token is burned). Rendered by Studio::LinksController#show
+  (consume_path: link_consume_path) — the engine's only token door since 0.31.0
+  — and by any app drawing its own token route. Rendered with layout false
+  (full document).
 
   Local: consume_path — the POST target that burns the token + signs in.
 %>

data/db/migrate/20260620000002_allow_null_image_cache_owner.rb

@@ -3,6 +3,16 @@
 # migration; each consumer app installs its own copy (the table is app-owned).
 class AllowNullImageCacheOwner < ActiveRecord::Migration[7.2]
   def change
+    # No-op on an app that doesn't use ImageCache. `image_caches` is app-owned,
+    # so an app can install the engine's migrations without having that table —
+    # and unguarded, this raised and failed the whole `db:migrate`.
+    #
+    # Deleting the copy is NOT a workaround: install:migrations builds its
+    # skip-list from the files PRESENT, so a deleted copy is re-copied with a
+    # fresh timestamp on the next upgrade and fails again. The guard has to live
+    # here, in the migration, or it doesn't hold.
+    return unless table_exists?(:image_caches)
+
     change_column_null :image_caches, :owner_type, true
     change_column_null :image_caches, :owner_id, true
   end

data/lib/studio/color_scale.rb

@@ -72,6 +72,19 @@ module Studio
       "#%02X%02X%02X" % [r.clamp(0, 255), g.clamp(0, 255), b.clamp(0, 255)]
     end
 
+    # WCAG 2.x relative luminance (sRGB linearized).
+    def self.relative_luminance(hex)
+      r, g, b = hex_to_rgb(hex).map { |c| c / 255.0 }
+      lin = [r, g, b].map { |c| c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055)**2.4 }
+      (0.2126 * lin[0]) + (0.7152 * lin[1]) + (0.0722 * lin[2])
+    end
+
+    # WCAG contrast ratio between two hex colors (1.0..21.0).
+    def self.contrast_ratio(a, b)
+      hi, lo = [relative_luminance(a), relative_luminance(b)].minmax.reverse
+      (hi + 0.05) / (lo + 0.05)
+    end
+
     def self.with_opacity(hex, opacity)
       r, g, b = hex_to_rgb(hex)
       "rgba(#{r},#{g},#{b},#{opacity})"

data/lib/studio/link_resolution.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "link_token"
+
+module Studio
+  # What a magic-link click should DO — the whole decision as one pure table,
+  # free of ActiveRecord and of the controller, so every cell is unit-testable.
+  #
+  # A click has three inputs: whether this caller BURNED the link (won the
+  # single-use race), whose email the link carries, and who is already signed
+  # in. Six cells fall out of that, and one invariant runs through them:
+  #
+  #   **A dead link never touches the session.**
+  #
+  # Before this table, every dead token — used, expired, or unknown — ended at
+  # `redirect_to login_path, alert: "invalid or has expired"`, whatever session
+  # the visitor was holding. So clicking your own link a second time dumped you
+  # on a sign-in page, which reads as being logged out. It never was: the cookie
+  # survived, but the destination said otherwise. Now a dead link is at worst a
+  # notice, and at best silent.
+  #
+  # The table (rows = link state, columns = who is signed in):
+  #
+  #                | nobody          | the link's own user | somebody else
+  #   -------------+-----------------+---------------------+------------------
+  #   live (burned)| :authenticate   | :continue           | :authenticate
+  #   used/expired | :dead → login   | :dead → return_to   | :dead → home
+  #   unknown token| :dead → login   |         —           | :dead → home
+  #
+  # `:continue` is the cell the operator asked for by name: a second click on
+  # your own still-live link must be "no material difference — just a redirect".
+  # It burns the token (so nobody replays it later) and deliberately does NOT
+  # re-authenticate, because a host that rotates the session on sign-in — as
+  # turf-monster does — would otherwise charge a re-click the price of every
+  # scrap of session state the visitor had built up.
+  module LinkResolution
+    # How the click found the link.
+    #   :claimed — this caller burned a live link (the only status that authenticates)
+    #   :used    — the row exists and was already consumed, or lost the burn race
+    #   :expired — the row exists and is past expires_at
+    #   :unknown — no row for this token, or the token is not a magic link
+    STATUSES = %i[claimed used expired unknown].freeze
+
+    # :authenticate — establish a session for the link's email (sign in or sign up)
+    # :continue     — the viewer already IS the link's user: keep the session as
+    #                 it stands and land them on the link's destination
+    # :dead         — do not touch the session at all
+    ACTIONS = %i[authenticate continue dead].freeze
+
+    # Where the click lands.
+    #   :return_to — the link's own destination (falling back to home)
+    #   :home      — the app root; used when the link belongs to someone else,
+    #                so its destination is not ours to follow
+    #   :login     — the sign-in page; only ever for a visitor with no session
+    DESTINATIONS = %i[return_to home login].freeze
+
+    Outcome = Struct.new(:action, :destination, :message, :level, keyword_init: true) do
+      def authenticate?
+        action == :authenticate
+      end
+
+      def continue?
+        action == :continue
+      end
+
+      def dead?
+        action == :dead
+      end
+
+      # A silent outcome shows the visitor nothing — the "no material
+      # difference" re-click.
+      def silent?
+        message.nil?
+      end
+    end
+
+    module_function
+
+    # @param status [Symbol] one of STATUSES
+    # @param link_email [String, nil] the email the link signs in (nil = unknown token)
+    # @param session_email [String, nil] the currently signed-in user's email
+    # @return [Outcome]
+    def call(status:, link_email: nil, session_email: nil)
+      raise ArgumentError, "unknown status #{status.inspect}" unless STATUSES.include?(status)
+
+      own = own_link?(link_email, session_email)
+
+      if status == :claimed
+        return Outcome.new(action: :continue, destination: :return_to) if own
+
+        # Nobody signed in, or somebody else signed in: both establish a session
+        # for the link's email. The second case is the deliberate account switch
+        # — a live link is proof of ownership, so it outranks the open session.
+        return Outcome.new(action: :authenticate, destination: :return_to)
+      end
+
+      # Dead from here down: no branch below may write to the session.
+      return Outcome.new(action: :dead, destination: :return_to) if own
+
+      if Studio::LinkToken.normalize_email(session_email).empty?
+        Outcome.new(action: :dead, destination: :login, level: :alert,
+                    message: dead_message(status: status, link_email: link_email))
+      else
+        Outcome.new(action: :dead, destination: :home, level: :notice,
+                    message: dead_message(status: status, link_email: link_email,
+                                          session_email: session_email))
+      end
+    end
+
+    # Same email, both sides present. A blank on either side is never a match —
+    # an unknown token (no email) must not read as "your own link" just because
+    # nobody is signed in.
+    def own_link?(link_email, session_email)
+      link = Studio::LinkToken.normalize_email(link_email)
+      seat = Studio::LinkToken.normalize_email(session_email)
+      !link.empty? && link == seat
+    end
+
+    # The notice a dead link earns. It names the address the link was for and
+    # why it failed — the detail that turns "something went wrong" into a
+    # decision the reader can act on — and, when a session is open, says so
+    # plainly, because the whole point is that nothing was lost.
+    def dead_message(status:, link_email: nil, session_email: nil)
+      addressee = Studio::LinkToken.normalize_email(link_email)
+      who = addressee.empty? ? "" : " for #{addressee}"
+      why = case status
+            when :expired then "has expired"
+            when :used    then "was already used"
+            else               "is no longer valid"
+            end
+
+      base = "That sign-in link#{who} #{why}."
+      seat = Studio::LinkToken.normalize_email(session_email)
+      return "#{base} Request a fresh one below." if seat.empty?
+
+      "#{base} You are still signed in as #{seat} — request a fresh link to switch accounts."
+    end
+  end
+end

data/lib/studio/link_token.rb

@@ -18,10 +18,19 @@ module Studio
     # they are deliberately NOT single-use.
     SINGLE_USE_KINDS = %w[magic_link].freeze
 
-    # 96 bits of entropy → ~16 URL-safe chars (e.g. "PP-PDbEj5V3-aNh4"). Short
-    # enough to keep the URL clean, far too large to brute-force — especially
-    # for single-use, expiring magic links. Matches turf-monster's proven format.
-    TOKEN_BYTES = 12
+    # THE HOUSE TOKEN STANDARD: 12 random bytes → exactly 16 URL-safe
+    # characters (e.g. "PP-PDbEj5V3-aNh4"). 96 bits of entropy — short enough
+    # that the whole link fits on one line of an email, far too large to
+    # brute-force, especially for a single-use token that expires in minutes.
+    #
+    # 16 sits mid-range in the house bound of 10-20 characters (TOKEN_LENGTH_
+    # BOUNDS), which is the number a reader should sanity-check a link against.
+    # urlsafe_base64 emits 4 characters per 3 bytes with no padding, so the
+    # length is exact, not approximate — every token is the same width.
+    TOKEN_BYTES  = 12
+    TOKEN_LENGTH = 16
+    TOKEN_LENGTH_BOUNDS = (10..20).freeze
+    TOKEN_FORMAT = /\A[A-Za-z0-9_-]+\z/
 
     module_function
 

data/lib/studio/theme_resolver.rb

@@ -39,8 +39,18 @@ module Studio
         "--color-inset"          => ColorScale.darken(dark_base, 0.43),
         "--color-text"           => "#ffffff",
         "--color-text-body"      => "#e2e8f0",
-        "--color-text-secondary" => "#94a3b8",
-        "--color-text-muted"     => "#64748b",
+        # Derived by a bounded contrast search, not hardcoded: fixed slate
+        # grays fail WCAG on themes whose dark base lifts the surface (a
+        # hardcoded #64748b measured 2.14:1 on a navy surface), and any FIXED
+        # blend amount is tuned to particular hexes — the operator can pick an
+        # arbitrary base in the theme editor. contrast_ink walks the blend up
+        # until the ink clears its target on every emitted dark surface
+        # (clamped at pure white for pathological bases). Note the blend
+        # DESATURATES toward gray; only strongly-tinted bases keep a cast.
+        "--color-text-secondary" => contrast_ink(dark_base, direction: :lighten, start: 0.70, target: 4.5,
+                                                 against: dark_surfaces(dark_base)),
+        "--color-text-muted"     => contrast_ink(dark_base, direction: :lighten, start: 0.55, target: 3.0,
+                                                 against: dark_surfaces(dark_base)),
         "--color-border"         => ColorScale.with_opacity(border_rgb, 0.2),
         "--color-border-strong"  => ColorScale.with_opacity(border_rgb, 0.4),
         "--color-shadow"         => "transparent",
@@ -48,10 +58,41 @@ module Studio
         "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
         "--color-success"        => colors[:success] || "#4BAF50",
         "--color-warning"        => colors[:warning] || "#FF7C47",
-        "--color-danger"         => colors[:danger] || "#EF4444"
+        "--color-danger"         => colors[:danger] || "#EF4444",
+        "--color-accent"         => colors[:accent] || "#F72585"
       }
     end
 
+    # Every dark-mode background a text var can sit on (page, surface,
+    # surface-alt, inset) — the ink must clear its target on ALL of them.
+    def dark_surfaces(dark_base)
+      [ dark_base,
+        ColorScale.lighten(dark_base, 0.15),
+        ColorScale.darken(dark_base, 0.14),
+        ColorScale.darken(dark_base, 0.43) ]
+    end
+
+    def light_surfaces(light_base)
+      [ light_base,
+        "#ffffff",
+        ColorScale.darken(light_base, 0.03),
+        ColorScale.darken(light_base, 0.08) ]
+    end
+
+    # Bounded, clamped search: raise the blend amount from `start` until the
+    # ink clears `target` contrast against every background in `against`.
+    # Clamps at 1.0 (pure white/black), so a pathological base degrades to the
+    # best achievable ink instead of looping.
+    def contrast_ink(base, direction:, start:, target:, against:)
+      amount = start
+      loop do
+        ink = direction == :lighten ? ColorScale.lighten(base, amount) : ColorScale.darken(base, amount)
+        return ink if against.all? { |bg| ColorScale.contrast_ratio(ink, bg) >= target } || amount >= 1.0
+
+        amount = [amount + 0.02, 1.0].min
+      end
+    end
+
     # Generate --color-primary-{50..900} + RGB variants for Tailwind opacity support
     def primary_palette_vars
       primary = colors[:primary] || "#8E82FE"
@@ -83,8 +124,13 @@ module Studio
         "--color-inset"          => ColorScale.darken(light_base, 0.08),
         "--color-text"           => "#0f172a",
         "--color-text-body"      => "#334155",
-        "--color-text-secondary" => "#64748b",
-        "--color-text-muted"     => "#94a3b8",
+        # Same bounded search as dark mode: the old fixed grays measured as
+        # low as 2.05:1 (muted on --color-inset) — below the very defect this
+        # derivation exists to prevent. Ink darkens away from the light base.
+        "--color-text-secondary" => contrast_ink(light_base, direction: :darken, start: 0.55, target: 4.5,
+                                                 against: light_surfaces(light_base)),
+        "--color-text-muted"     => contrast_ink(light_base, direction: :darken, start: 0.40, target: 3.0,
+                                                 against: light_surfaces(light_base)),
         "--color-border"         => ColorScale.darken(light_base, 0.08),
         "--color-border-strong"  => ColorScale.darken(light_base, 0.15),
         "--color-shadow"         => "rgba(0,0,0,0.05)",
@@ -92,7 +138,8 @@ module Studio
         "--color-cta-hover"      => ColorScale.darken(primary, 0.30),
         "--color-success"        => colors[:success] || "#4BAF50",
         "--color-warning"        => colors[:warning] || "#FF7C47",
-        "--color-danger"         => colors[:danger] || "#EF4444"
+        "--color-danger"         => colors[:danger] || "#EF4444",
+        "--color-accent"         => colors[:accent] || "#F72585"
       }
     end
   end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.30.0"
+  VERSION = "0.32.0"
 end

data/lib/studio.rb

@@ -9,6 +9,7 @@ require "studio/username_generator"
 require "studio/s3"
 require "studio/image_cache"
 require "studio/link_token"
+require "studio/link_resolution"
 require "studio/email"
 require "studio/email_smoke"
 require "studio/mail_transport"
@@ -80,18 +81,40 @@ module Studio
   #   end
   mattr_accessor :sidebar_sections, default: []
 
-  # Magic-link (passwordless email) tuning. token_name keys the MessageVerifier
-  # purpose; bump it to invalidate every outstanding link. See MagicLink service.
-  mattr_accessor :magic_link_ttl,        default: 15.minutes
+  # How long a freshly minted magic link stays live.
+  mattr_accessor :magic_link_ttl, default: 15.minutes
+
+  # RETIRED (0.31.0) — kept only so an initializer that still sets it boots.
+  # It named the MessageVerifier purpose for the old :signed store, which no
+  # longer exists. Delete the line from your initializer.
   mattr_accessor :magic_link_token_name, default: "magic_link_v1"
 
-  # Where magic-link tokens are stored / which URL scheme they use.
-  #   :signed   (default) — stateless MessageVerifier MagicLink service; URL is
-  #             /magic_link/<long token>. No table needed. Back-compat default.
-  #   :database — a Studio::Link row; URL is the short /l/<token>. Requires the
-  #             studio_links table (install the reference migration). The
-  #             unified scheme both apps move to.
-  mattr_accessor :magic_link_store, default: :signed
+  # RETIRED (0.31.0) — magic links are ALWAYS Studio::Link rows now, so this
+  # reads :database and nothing else. Assigning :signed raises rather than
+  # silently downgrading: that store minted a ~350-character MessageVerifier
+  # blob whose EXPIRED form cannot be decoded, so an app on it could not tell
+  # whose dead link it was holding — which is exactly the fact
+  # Studio::LinkResolution needs to leave a live session alone. Requires the
+  # studio_links table, installed by `bin/rails studio_engine:install:migrations`
+  # (never hand-copied — a hand copy collides with the task's own copy on
+  # `class CreateStudioLinks`).
+  mattr_reader :magic_link_store, default: :database
+
+  # `to_s.to_sym`, not `to_sym`: this runs from an initializer, and nil or an
+  # Integer would raise NoMethodError — swallowing the explanation below with a
+  # message that says nothing about what to do. A blank falls through to the
+  # raise instead, so the operator reads the actual instruction.
+  def self.magic_link_store=(value)
+    return if value.to_s.to_sym == :database
+
+    raise ArgumentError,
+          "Studio.magic_link_store = #{value.inspect} is retired (studio-engine 0.31.0). " \
+          "Magic links are Studio::Link rows served at /l/<token>. Delete this line from " \
+          "config/initializers/studio.rb, then install the table with " \
+          "`bin/rails studio_engine:install:migrations && bin/rails db:migrate` — in that " \
+          "order, because this raise fires while the initializer loads and no rake task can " \
+          "boot until the line is gone."
+  end
 
   # Whether Studio.routes draws the magic_link + solana wallet routes. An app that
   # already defines its own auth routes (e.g. turf-monster, which has battle-tested
@@ -229,13 +252,13 @@ module Studio
     false
   end
 
-  # True when the emailed/inbox magic-link URL is the short /l/<token> — i.e.
-  # magic links are Studio::Link rows AND this app draws the /l routes. False =
-  # the legacy /magic_link/<token> path: the :signed store, OR an app on the
-  # :database store that keeps its own /magic_link route (e.g. turf-monster,
-  # whose /l is already its landing-page namespace).
+  # True when the emailed/inbox magic-link URL is the short /l/<token> — the
+  # standard. False means this app draws its own token route instead and owns
+  # the matching consume: turf-monster keeps /magic_link/<token> because /l is
+  # already its landing-page namespace. Either way the TOKEN is the same short
+  # Studio::Link token; only the path in front of it differs.
   def self.magic_link_via_l_route?
-    magic_link_store == :database && draw_link_routes
+    draw_link_routes
   end
 
   # The floor every developer-desk tool sits on: the local email inbox
@@ -393,18 +416,15 @@ module Studio
         get "_studio/local_review", to: "studio/local_reviews#show",  as: :studio_local_review
       end
 
-      # Passwordless email (magic link). Helpers: magic_link_request_path (POST
-      # to request a link), magic_link_path(token) / magic_link_url(token:)
-      # for the emailed GET confirmation page, and magic_link_consume_path(token)
-      # for the scanner-safe POST consume. The token is a URL-safe
-      # MessageVerifier blob but the constraint guards against a stray "."
-      # segment.
+      # Passwordless email (magic link) — the REQUEST half only. Helper:
+      # magic_link_request_path (POST an email address, get a link mailed).
+      #
+      # The token-bearing half moved to /l/<token> below (0.31.0). There is one
+      # token format now — a short Studio::Link row — and one place that burns
+      # it, so the old /magic_link/:token confirm+consume pair would have been a
+      # second door onto the same lock.
       if Studio.draw_auth_routes && Studio.auth_method?(:magic_link)
-        post "magic_link",        to: "magic_links#create",   as: :magic_link_request
-        get  "magic_link/:token", to: "magic_links#confirm",  as: :magic_link,
-             constraints: { token: %r{[^/]+} }
-        post "magic_link/:token", to: "magic_links#consume",  as: :magic_link_consume,
-             constraints: { token: %r{[^/]+} }
+        post "magic_link", to: "magic_links#create", as: :magic_link_request
       end
 
       # Unified short-token links — /l/<token> for magic sign-in links + referral