where_is_waldo 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce4ac18944bec996440772eed972216ff64975a1be13b4f7f3d0230e5cc0807f
-  data.tar.gz: 80e1f0ba820d24dc5f5d74f7ef4cc31e00ba3f183145d24de17dc24e5bd4b78b
+  metadata.gz: e9b514019f64edaaea98c2d51266e3668f5a3bd270c5727013bb38bd7db51232
+  data.tar.gz: c4313e9f5f1f05b3640c2e019dcbe7883f4a59f027944f6395878baa60bdfdf4
 SHA512:
-  metadata.gz: 877c8e0adf85cb7c8e75f992939c372690d1a928ab3ef4b6a4d64479ba9801ccd74820235db112d4efcab473a0589097165b62edf07824247a1a6be82d6ba32a
-  data.tar.gz: d91ec5e623c3a8e8b7b149d5d9a80d6110ab5f4a8c81cc71bdaa73608afc593efe534bc2dc53c71df067837fb56c1cac9479df52a421f7364d1b545cc7657018
+  metadata.gz: 02aaa7a93acfa3c4732eec460b1fad4f6361dc0c64e9ed60539914b025d785db4dd4ed8acb8b0e55ae92a4cda116c31acb1f46745c1567196b461470b2ea8e27
+  data.tar.gz: 955493cf1cab229f550e25ffc3a8e54069ba297bf9bf9e0ee6ed0acc5e092bae61c00278b684a44d14833fe23210b0b35409fc2a09f6234cabcd10df2a44bf91

data/CHANGELOG.md

@@ -3,6 +3,91 @@
 Notable changes to where_is_waldo. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## Unreleased
+
+## 0.1.12 - 2026-10-27
+
+### Fixed
+
+- **A subject in more than one org could be put on the wrong roster.**
+  `roster_org` receives only the subject, so an app whose users belong to
+  several orgs had to guess, and the obvious guess (`accounts.first`) is
+  association order rather than the org the person is actually working in.
+  They were then invisible to the teammates they were with, and shown to an
+  org they were not in.
+
+  New `roster_org_for` receives `(subject, container)`, where the container is
+  the one the CONNECTION is scoped to -- the only place that answer exists. It
+  applies on BOTH sides: the presence row stores the resolved org at connect
+  and later broadcasts read it back, and the roster subscription resolves the
+  same way, so a viewer and the broadcasts meant for them can no longer land
+  on different streams. `container` comes from your connection's
+  `identified_by :current_container`; without that it is nil and behaviour is
+  unchanged. A subject present in two
+  orgs now appears in both rosters rather than one arbitrary one.
+
+  Stored in the existing `metadata` column, so **no migration is required**.
+  `roster_org` is untouched and still works for single-org apps.
+
+- **A presence transition read a subject's sessions twice.** Publishing needs
+  both the org keys and the aggregate state, and both come from the same rows;
+  they are now derived from one read. This is the hottest path in the library,
+  so the second read was pure overhead.
+
+
+## 0.1.11 - 2026-10-27
+
+### Fixed
+
+- **The install generator emitted the pre-0.1.5 schema.** It wrote a unique
+  index on the session column alone, while 0.1.5 moved presence rows to being
+  keyed by `(subject, session)` precisely so two authenticated subjects who
+  collide on a session id cannot upsert onto each other's row — session ids are
+  client-supplied in some setups, and a reused JWT `jti` is enough. The adapter
+  has scoped every session lookup by both columns since; only the generator
+  lagged, so every app installed after 0.1.5 got a schema the library had
+  already moved away from and needed a follow-up migration to correct. An
+  unused second migration template carrying the right index (and a hardcoded
+  `Migration[7.0]`) has been removed rather than left as a second answer.
+
+- **The install generator overwrote an existing ActionCable connection.**
+  Installing into an app that already authenticates its own cable connection
+  replaced that file with the turnkey one, silently dropping whatever the app
+  did beyond what this library needs — container scoping and token bookkeeping
+  in the cases seen. Existing channel files are now kept, and the post-install
+  message names them and states what the channel requires of a connection
+  (`current_user` and `session_id`).
+
+### Changed
+
+- **The Redis adapter is now tested against a real server, on both redis-rb 5
+  and 6.** Its existing spec runs against `MockRedis`, a pure-Ruby fake with no
+  protocol layer, so it could not see wire-format changes at all. redis-rb 6
+  defaults to RESP3, which types several replies differently from RESP2 —
+  `SMEMBERS` among them, and this adapter feeds that result straight into
+  `filter_map` and `all?`. Nothing in the adapter's command set behaves
+  differently between the two, but that was previously unverified rather than
+  known.
+
+  - New integration spec drives the adapter against a live Redis. It skips when
+    no server is reachable, so contributors are not required to run one.
+  - CI adds an `rspec-redis` job with a Redis service, run as a matrix over
+    redis-rb 5.x and 6.x, and fails rather than skips if the service is missing
+    — a silent skip would read as a pass.
+  - Development dependency widened from `~> 5.0` to `>= 5.0, < 7`. The gem has
+    no runtime dependency on `redis` and never has, so this constrains nothing
+    for consumers; it only lets the library test what consumers actually use.
+  - README documents supported client versions, and that `protocol: 2` is not
+    needed.
+
+  The committed lockfile stays on redis 5.x, which keeps `mock_redis` at
+  0.53.0 for every existing spec. `mock_redis` 0.53.0 depends on `redis ~> 5`,
+  so resolving against redis 6 forces it down to 0.48.1 — that happens only
+  inside the redis 6 CI leg, which runs the real-server spec alone and never
+  touches MockRedis. No mock-based spec changed the double it runs against.
+
+  No runtime code changed.
+
 ## 0.1.10
 
 ### Added

data/README.md

@@ -41,6 +41,13 @@ rails generate where_is_waldo:install --adapter=redis --subject_column=user_id
 npm install @byscott-io/where-is-waldo @rails/actioncable
 ```
 
+Installing into an app that already has `app/channels/application_cable/`?
+Those files are kept, never overwritten — the generator only adds what is
+missing, and says which it left alone. The presence channel needs the
+connection to identify **`current_user`** and **`session_id`**; add them to
+your own connection, or `include WhereIsWaldo::JwtConnection` (corebyscott
+apps) to get both from the JWT.
+
 ### 2. Configure
 
 ```ruby
@@ -148,6 +155,20 @@ WhereIsWaldo.configure do |config|
 end
 ```
 
+#### Redis adapter and client versions
+
+The gem does not depend on `redis`. Choosing `:redis` means supplying your own
+client, so you pick the version.
+
+`redis-rb` 5.x and 6.x are both supported and both run in CI against a real
+server. Version 6 switched to RESP3 by default, which changes reply types for
+some commands; none of the commands this adapter uses behave differently, and
+the integration spec exists to keep that true. Nothing here needs `protocol: 2`.
+
+The adapter stores presence under keys prefixed by `config.redis_prefix`
+(default `where_is_waldo`) and sets a TTL on session keys, so it does not need a
+cleanup job the way the database adapter does.
+
 ### Querying Presence
 
 ```ruby
@@ -269,6 +290,32 @@ their live sessions (multiple browser tabs, mobile, etc.):
 WhereIsWaldo.configure do |config|
   # The org/account a subject belongs to. Required to enable the roster.
   config.roster_org = ->(subject) { subject.account }
+  #
+  # MULTI-ORG SUBJECTS: roster_org is handed only the subject, so it has to
+  # guess which org the person is in right now -- and `accounts.first` guesses
+  # by association order. Someone who has switched is then put on the wrong
+  # roster: invisible to the teammates they are with, shown to an org they are
+  # not in. Use roster_org_for instead, which also receives the container the
+  # CONNECTION is scoped to:
+  #
+  #   config.roster_org_for = ->(user, container) { container || user.accounts.first }
+  #
+  # `container` is read from your own ActionCable connection, so it is only
+  # ever non-nil if that connection identifies one:
+  #
+  #   module ApplicationCable
+  #     class Connection < ActionCable::Connection::Base
+  #       identified_by :current_user, :current_container, :session_id
+  #     end
+  #   end
+  #
+  # WhereIsWaldo::JwtConnection already does this. Without it `container` is
+  # always nil and the fallback above behaves exactly like plain roster_org --
+  # which is to say, like the bug.
+  #
+  # The resolved org is stored on the presence row at connect and read back by
+  # later broadcasts, so the subscriber and the broadcaster always agree on the
+  # stream. roster_org keeps working unchanged for single-org apps.
 
   # What a VIEWER may see (:poll/:nudge/:fanout). Any visibility rule,
   # server-enforced. Defaults to the viewer's whole org when unset.

data/VERSION

@@ -1 +1 @@
-0.1.10
+0.1.12

data/app/channels/where_is_waldo/presence_channel.rb

@@ -88,13 +88,43 @@ module WhereIsWaldo
     end
 
     def register_presence
+      # The org key is computed HERE and written over anything the client sent.
+      # params[:metadata] is client-supplied, so letting a tab name its own
+      # roster would let it subscribe itself into an org it has no business
+      # seeing.
+      #
+      # The client's value is REMOVED FIRST, unconditionally. Only overwriting
+      # it when the server resolves an org leaves the hole open in exactly the
+      # case that matters: a connection with no org of its own could name any
+      # org it liked, the value would persist on the presence row, and later
+      # broadcasts read it back verbatim and push that subject's presence into
+      # a stream they have no claim on.
+      metadata = (params[:metadata] || {}).to_h
+      metadata.delete(WhereIsWaldo::Roster::ORG_KEY)
+      metadata.delete(WhereIsWaldo::Roster::ORG_KEY.to_sym)
+
+      key = WhereIsWaldo::Roster.org_key(wiw_connection_org)
+      metadata[WhereIsWaldo::Roster::ORG_KEY] = key if key
+
       WhereIsWaldo.connect(
         session_id: waldo_session_id,
         subject_id: waldo_subject_id,
-        metadata: params[:metadata] || {}
+        metadata: metadata
       )
     end
 
+    # The org this CONNECTION is scoped to. The container comes from the host
+    # app's own cable connection, which is the only place that knows the org
+    # the person is actually working in -- a lambda given just the subject has
+    # to guess, and guesses by association order.
+    def wiw_connection_org
+      return @wiw_connection_org if defined?(@wiw_connection_org)
+
+      subject = WhereIsWaldo.config.subject_class_constant&.find_by(id: waldo_subject_id)
+      container = connection.try(:current_container)
+      @wiw_connection_org = subject && WhereIsWaldo.config.resolve_roster_org(subject, container: container)
+    end
+
     def roster_transition?(tab_visible, subject_active)
       tab_visible != @wiw_tab_visible || subject_active != @wiw_subject_active
     end
@@ -104,8 +134,7 @@ module WhereIsWaldo
     def resolve_roster_strategy
       return nil unless WhereIsWaldo.config.roster_enabled?
 
-      subject = WhereIsWaldo.config.subject_class_constant&.find_by(id: waldo_subject_id)
-      org = subject && WhereIsWaldo.config.resolve_roster_org(subject)
+      org = wiw_connection_org
       return nil unless org
 
       WhereIsWaldo::RosterDelivery.for(WhereIsWaldo.config.resolve_mode(org))

data/app/channels/where_is_waldo/roster_channel.rb

@@ -13,12 +13,15 @@ module WhereIsWaldo
   class RosterChannel < ApplicationCable::Channel
     def subscribed
       subject = current_subject
-      mode = resolve_mode(subject)
+      org = resolve_org(subject)
+      return reject unless org
+
+      mode = WhereIsWaldo.config.resolve_mode(org)
       return reject unless mode
 
       @wiw_subject = subject
       @wiw_strategy = RosterDelivery.for(mode)
-      apply_plan(@wiw_strategy.subscribe_plan(subject, waldo_session_id))
+      apply_plan(@wiw_strategy.subscribe_plan(subject, waldo_session_id, org: org))
     end
 
     # Client-driven poll (pull/nudge modes). Transmits a filtered snapshot
@@ -31,11 +34,15 @@ module WhereIsWaldo
 
     private
 
-    def resolve_mode(subject)
-      org = WhereIsWaldo.config.resolve_roster_org(subject)
-      return nil unless org
+    # The org this VIEWER is watching. Resolved from the connection's container
+    # like the writer side, so the stream they subscribe to is the one deltas
+    # are actually broadcast into. Resolving from the subject alone here was
+    # the other half of the same bug: a viewer scoped to their second org sat
+    # on their first org's stream and simply never saw anything.
+    def resolve_org(subject)
+      return nil unless subject
 
-      WhereIsWaldo.config.resolve_mode(org)
+      WhereIsWaldo.config.resolve_roster_org(subject, container: connection.try(:current_container))
     end
 
     def apply_plan(plan)

data/app/services/where_is_waldo/roster/org_keys.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module WhereIsWaldo
+  class Roster
+    # Which roster a session belongs to, and how that is stored.
+    #
+    # Extracted from Roster so the resolution rules sit together and can be
+    # read without the delivery machinery around them.
+    module OrgKeys
+      # WHICH ROSTER A SESSION BELONGS TO IS DECIDED ONCE, AT CONNECT, AND
+      # STORED ON THE PRESENCE ROW.
+      #
+      # It cannot be re-derived later. The connection knows the container the
+      # person is actually working in; a background broadcast an hour later has
+      # only a subject id, and a subject can belong to several orgs. Deriving
+      # it twice is how the subscriber ends up listening to one stream while
+      # the broadcaster writes to another -- which looks exactly like presence
+      # being broken, not like a resolution bug.
+      #
+      # Stored in metadata rather than a column so this needs no migration in
+      # any consuming app.
+      def org_key(org)
+        return nil unless org
+
+        klass = org.class.respond_to?(:base_class) ? org.class.base_class : org.class
+        "#{klass.name}:#{org.id}"
+      end
+
+      def org_from_key(key)
+        type, id = key.to_s.split(":", 2)
+        return nil if type.blank? || id.blank?
+
+        type.safe_constantize&.find_by(id: id)
+      rescue StandardError
+        nil
+      end
+
+      # Every org this subject is currently connected in -- usually one, but a
+      # person with two tabs in two accounts is present in both and must appear
+      # in both rosters. Falls back to resolving from the subject alone for
+      # rows written before this existed, and for apps with no container.
+      def org_keys_for_subject(subject_id, timeout: nil)
+        by_subject = WhereIsWaldo::PresenceService.sessions_for_subjects([subject_id], timeout: timeout)
+        org_keys_from(sessions_for(by_subject, subject_id), subject_id)
+      end
+
+      # The same answer from sessions the caller has ALREADY loaded. A presence
+      # transition needs both the org keys and the subject's aggregate state,
+      # and both are derived from one set of session rows -- reading them twice
+      # doubles the adapter traffic on the hottest path in the library.
+      def org_keys_from(sessions, subject_id)
+        keys = sessions.filter_map do |session|
+          session.dig(:metadata, ORG_KEY) || session.dig("metadata", ORG_KEY)
+        end.uniq
+        return keys if keys.any?
+
+        [org_key(WhereIsWaldo.config.resolve_roster_org(find_subject(subject_id)))].compact
+      end
+
+      private
+
+      # THE KEY TYPES ON THE TWO SIDES ARE NOT GUARANTEED TO MATCH.
+      #
+      # The database adapter keys its result by the AR-typecast column value,
+      # typically an Integer, while a subject id arriving from a cable
+      # connection is often a String -- authenticate_proc returns whatever the
+      # host app decides, and connection params are strings. A plain fetch then
+      # misses, and the caller falls back to resolving from the subject alone:
+      # silently, and straight back to the guess this exists to replace.
+      # Comparing as strings is what stops a type difference becoming a wrong
+      # roster.
+      def sessions_for(by_subject, subject_id)
+        return by_subject[subject_id] if by_subject.key?(subject_id)
+
+        wanted = subject_id.to_s
+        _, sessions = by_subject.find { |key, _| key.to_s == wanted }
+        sessions || []
+      end
+    end
+  end
+end

data/app/services/where_is_waldo/roster.rb

@@ -34,6 +34,13 @@ module WhereIsWaldo
     RANK = { active: 3, idle: 2, background: 1, offline: 0 }.freeze
     DEFAULT_PLATFORM = "web"
 
+    # The metadata key holding which roster a session belongs to. Defined on
+    # the class, not the singleton, so callers can reference
+    # WhereIsWaldo::Roster::ORG_KEY.
+    ORG_KEY = "wiw_org"
+
+    extend OrgKeys
+
     class << self
       # Shared stream name for an org record (nil when org is absent).
       def stream_name(org)
@@ -45,8 +52,8 @@ module WhereIsWaldo
 
       # Shared stream name for the org a subject belongs to (nil when the roster
       # is unconfigured or the subject has no org).
-      def stream_for_subject(subject)
-        stream_name(WhereIsWaldo.config.resolve_roster_org(subject))
+      def stream_for_subject(subject, container: nil)
+        stream_name(WhereIsWaldo.config.resolve_roster_org(subject, container: container))
       end
 
       # Full roster state for an org: every member subject with their current
@@ -118,12 +125,23 @@ module WhereIsWaldo
       def publish(subject_id, timeout: nil)
         return false if subject_id.blank?
 
-        subject = find_subject(subject_id)
-        stream = stream_name(WhereIsWaldo.config.resolve_roster_org(subject))
-        return false unless stream
+        # ONE read of the subject's sessions, used for both halves. The org
+        # keys and the aggregate state are derived from the same rows, and a
+        # transition is the hottest path here -- fetching twice doubled the
+        # adapter traffic for no new information.
+        by_subject = WhereIsWaldo::PresenceService.sessions_for_subjects([subject_id], timeout: timeout)
+        sessions = sessions_for(by_subject, subject_id)
 
-        member = build_member_by_id(subject, subject_id, timeout: timeout)
-        ActionCable.server.broadcast(stream, delta_message(member))
+        keys = org_keys_from(sessions, subject_id)
+        return false if keys.empty?
+
+        subject = find_subject(subject_id)
+        state = sessions.any? ? aggregate(sessions) : offline_state
+        member = merge_member(subject, state, id: subject_id)
+        keys.each do |key|
+          stream = "where_is_waldo:roster:#{key}"
+          ActionCable.server.broadcast(stream, delta_message(member))
+        end
         true
       rescue StandardError => e
         Rails.logger&.warn("[WhereIsWaldo::Roster] publish failed for #{subject_id}: #{e.class}: #{e.message}")
@@ -158,11 +176,10 @@ module WhereIsWaldo
       def publish_nudge(subject_id)
         return false if subject_id.blank?
 
-        subject = find_subject(subject_id)
-        stream = stream_name(WhereIsWaldo.config.resolve_roster_org(subject))
-        return false unless stream
+        keys = org_keys_for_subject(subject_id)
+        return false if keys.empty?
 
-        ActionCable.server.broadcast(stream, nudge_message)
+        keys.each { |key| ActionCable.server.broadcast("where_is_waldo:roster:#{key}", nudge_message) }
         true
       rescue StandardError => e
         Rails.logger&.warn("[WhereIsWaldo::Roster] nudge failed for #{subject_id}: #{e.class}: #{e.message}")

data/app/services/where_is_waldo/roster_delivery.rb

@@ -28,7 +28,7 @@ module WhereIsWaldo
     # Base contract. Channels call these; return values drive the channel's I/O.
     class Base
       # @return [Hash] { streams: [names], messages: [cable messages] }
-      def subscribe_plan(_subject, _session_id)
+      def subscribe_plan(_subject, _session_id, org: nil) # rubocop:disable Lint/UnusedMethodArgument
         { streams: [], messages: [] }
       end
 
@@ -50,8 +50,11 @@ module WhereIsWaldo
     # Instant push to a single shared per-account stream. NO visibility
     # filtering — everyone in the account sees everyone. O(1) per transition.
     class Broadcast < Base
-      def subscribe_plan(subject, _session_id)
-        org = config.resolve_roster_org(subject)
+      def subscribe_plan(subject, _session_id, org: nil)
+        # org comes from the channel, which knows the connection's container.
+        # Resolving it again here would reach a different answer for a subject
+        # in several orgs, and put the viewer on a stream nobody broadcasts to.
+        org ||= config.resolve_roster_org(subject)
         stream = Roster.stream_name(org)
         return { streams: [], messages: [] } unless stream
 
@@ -77,10 +80,13 @@ module WhereIsWaldo
         :poll
       end
 
-      def subscribe_plan(subject, session_id)
+      def subscribe_plan(subject, session_id, org: nil)
         current = current_members(subject)
         write_baseline(session_id, current)
-        { streams: subscribe_streams(subject), messages: [Roster.snapshot_message(current.values, mode: mode)] }
+        {
+          streams: subscribe_streams(subject, org: org),
+          messages: [Roster.snapshot_message(current.values, mode: mode)]
+        }
       end
 
       def poll_messages(subject, session_id)
@@ -101,7 +107,7 @@ module WhereIsWaldo
 
       # Streams to subscribe on connect. :poll needs none (data rides the poll
       # transmit); :nudge overrides this to also receive the account nudge.
-      def subscribe_streams(_subject)
+      def subscribe_streams(_subject, org: nil) # rubocop:disable Lint/UnusedMethodArgument
         []
       end
 
@@ -156,8 +162,9 @@ module WhereIsWaldo
       private
 
       # Also subscribe the account stream so this client receives nudges.
-      def subscribe_streams(subject)
-        stream = Roster.stream_name(config.resolve_roster_org(subject))
+      def subscribe_streams(subject, org: nil)
+        org ||= config.resolve_roster_org(subject)
+        stream = Roster.stream_name(org)
         stream ? [stream] : []
       end
     end
@@ -168,7 +175,7 @@ module WhereIsWaldo
     # its directional audience (config.roster_viewers_of). O(audience) per
     # transition — the price of instant delivery under restricted visibility.
     class Fanout < Base
-      def subscribe_plan(subject, _session_id)
+      def subscribe_plan(subject, _session_id, org: nil) # rubocop:disable Lint/UnusedMethodArgument
         members = Roster.members_for(config.resolve_visible_to(subject))
         {
           streams: [Roster.viewer_stream(subject.id)],

data/lib/generators/where_is_waldo/install/install_generator.rb

@@ -32,9 +32,17 @@ module WhereIsWaldo
       end
 
       def create_channels
-        template "connection.rb.tt", "app/channels/application_cable/connection.rb"
-        template "channel.rb.tt", "app/channels/application_cable/channel.rb"
-        template "presence_channel.rb.tt", "app/channels/presence_channel.rb"
+        # NEVER overwrite an app's existing cable connection or channel base.
+        # A host app that already authenticates ActionCable has its auth,
+        # container scoping and session identity in those files, and the
+        # turnkey versions here provide only what this library needs -- so
+        # replacing them silently drops whatever else they did. Installing
+        # into an existing app is the common case, not the exception.
+        @kept_channels = []
+
+        copy_channel "connection.rb.tt", "app/channels/application_cable/connection.rb"
+        copy_channel "channel.rb.tt", "app/channels/application_cable/channel.rb"
+        copy_channel "presence_channel.rb.tt", "app/channels/presence_channel.rb"
       end
 
       def show_post_install_message
@@ -54,10 +62,34 @@ module WhereIsWaldo
         say "       <App />"
         say "     </PresenceProvider>"
         say ""
+        report_kept_channels
       end
 
       private
 
+      # Say plainly what was left alone. A silent skip is as confusing as a
+      # silent overwrite: the install looks complete and presence then fails
+      # because the app's own connection exposes no session identity.
+      def report_kept_channels
+        return if @kept_channels.blank?
+
+        say "Kept your existing files (not overwritten):", :yellow
+        @kept_channels.each { |f| say "  - #{f}" }
+        say ""
+        say "  WhereIsWaldo's channel reads connection.current_user and"
+        say "  connection.session_id. If your connection does not identify"
+        say "  both, add them -- or include WhereIsWaldo::JwtConnection."
+        say ""
+      end
+
+      def copy_channel(source, destination)
+        if File.exist?(File.join(destination_root, destination))
+          @kept_channels << destination
+        else
+          template source, destination
+        end
+      end
+
       def migration_version
         "[#{ActiveRecord::VERSION::STRING.to_f}]"
       end

data/lib/generators/where_is_waldo/install/templates/migration.rb.tt

@@ -14,7 +14,12 @@ class CreatePresences < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
 
-    add_index :presences, :<%= session_column %>, unique: true
+    # (subject, session) must be unique TOGETHER, never session alone. Session
+    # ids are not globally unique -- they are client-supplied in some setups,
+    # and a reused JWT jti is enough -- so keying on the session alone lets two
+    # authenticated subjects upsert onto each other's presence row. This is the
+    # keying the adapter uses: every session lookup scopes by both columns.
+    add_index :presences, [ :<%= subject_column %>, :<%= session_column %> ], unique: true
     add_index :presences, :last_heartbeat
   end
 end

data/lib/where_is_waldo/configuration.rb

@@ -83,6 +83,16 @@ module WhereIsWaldo
     # roster_members_association: association used to build the default roster
     #   from the org when roster_members is unset (defaults to the pluralized
     #   subject_class, e.g. :users).
+    # roster_org_for: the container-aware form of roster_org. Receives
+    #   (subject, container) where container is the one the CONNECTION is
+    #   scoped to -- the account the person is actually working in, which a
+    #   subject-only lambda cannot know. Prefer this whenever subjects can
+    #   belong to more than one org; roster_org picks by association order,
+    #   which puts a switched user on the wrong roster: invisible to the
+    #   teammates they are with, visible to an org they are not.
+    #     config.roster_org_for = ->(user, container) { container || user.accounts.first }
+    attr_accessor :roster_org_for
+
     attr_accessor :roster_org, :roster_members, :roster_members_association
 
     # roster_visible_to: given a VIEWER, return the AR scope of subjects
@@ -142,6 +152,7 @@ module WhereIsWaldo
 
       # Presence roster (set per app to enable)
       @roster_org = nil
+      @roster_org_for = nil
       @roster_members = nil
       @roster_members_association = nil
       @roster_visible_to = nil
@@ -165,10 +176,17 @@ module WhereIsWaldo
     end
 
     # Resolve the org/container record for a subject (nil if unset/absent).
-    def resolve_roster_org(subject)
-      return nil unless roster_org && subject
-
-      roster_org.call(subject)
+    # @param container [Object, nil] the connection's container, when known.
+    #   Only roster_org_for receives it; roster_org keeps its old arity so
+    #   existing apps are untouched.
+    def resolve_roster_org(subject, container: nil)
+      return nil unless subject
+
+      if roster_org_for
+        roster_org_for.call(subject, container)
+      elsif roster_org
+        roster_org.call(subject)
+      end
     end
 
     # Association name used to derive the default roster from an org when
@@ -193,7 +211,7 @@ module WhereIsWaldo
 
     # True when the live-presence roster feature is configured.
     def roster_enabled?
-      !roster_org.nil?
+      !roster_org.nil? || !roster_org_for.nil?
     end
 
     # Resolve the AR scope of subjects a VIEWER may see. Defaults to the

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: where_is_waldo
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Scott Gibson
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -84,16 +83,22 @@ dependencies:
   name: redis
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -206,11 +211,11 @@ files:
 - app/services/where_is_waldo/broadcaster.rb
 - app/services/where_is_waldo/presence_service.rb
 - app/services/where_is_waldo/roster.rb
+- app/services/where_is_waldo/roster/org_keys.rb
 - app/services/where_is_waldo/roster_delivery.rb
 - lib/generators/where_is_waldo/install/install_generator.rb
 - lib/generators/where_is_waldo/install/templates/channel.rb.tt
 - lib/generators/where_is_waldo/install/templates/connection.rb.tt
-- lib/generators/where_is_waldo/install/templates/create_presences.rb.tt
 - lib/generators/where_is_waldo/install/templates/initializer.rb.tt
 - lib/generators/where_is_waldo/install/templates/migration.rb.tt
 - lib/generators/where_is_waldo/install/templates/presence_channel.rb.tt
@@ -228,7 +233,6 @@ metadata:
   changelog_uri: https://github.com/byscott-io/where_is_waldo/blob/master/CHANGELOG.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -243,8 +247,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Real-time presence tracking for Rails + React applications
 test_files: []

data/lib/generators/where_is_waldo/install/templates/create_presences.rb.tt

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-class Create<%= table_name.camelize %> < ActiveRecord::Migration[7.0]
-  def change
-    create_table :<%= table_name %> do |t|
-      # Identifiers - column names are configurable
-      t.string :<%= session_column %>, null: false    # Unique session/connection identifier
-      t.bigint :<%= subject_column %>, null: false    # Who (user, member, student, etc.)
-
-      # Timestamps
-      t.datetime :connected_at, null: false
-      t.datetime :last_heartbeat, null: false
-      t.datetime :last_activity
-
-      # Activity state
-      t.boolean :tab_visible, default: true, null: false
-      t.boolean :subject_active, default: true, null: false
-
-      # Extensible metadata
-      t.<%= json_column_type %> :metadata
-
-      t.timestamps
-    end
-
-    # (subject, session) must be unique together. Keying by session alone
-    # would let two authenticated subjects that happen to collide on a
-    # session id (client-supplied values, JWT jti reuse, etc.) upsert onto
-    # each other's row.
-    add_index :<%= table_name %>, [:<%= subject_column %>, :<%= session_column %>], unique: true
-
-    # Session lookups (heartbeat, disconnect, session_status) always scope
-    # by (subject, session); the composite unique index above serves those.
-    # Query by subject alone
-    add_index :<%= table_name %>, :<%= subject_column %>
-
-    # Cleanup old records
-    add_index :<%= table_name %>, :last_heartbeat
-
-<% if subject_table.present? -%>
-    # Foreign key to subject table
-    add_foreign_key :<%= table_name %>, :<%= subject_table %>, column: :<%= subject_column %>
-<% end -%>
-  end
-end