ask-guests 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47d3aa99bde7a4fba72632740871294a132d06a492d679c78d5487daa5857506
-  data.tar.gz: 6f937c5d724bd72b036faed46a1490129b37ee59380da63d8ba781b2f243b9db
+  metadata.gz: 8bec805817f573f8d9fcbc2b5e7bc7c0e6622aed391b4af6d61f02c3544f1c10
+  data.tar.gz: 381594c955f847741546177fc5bb03ead0e71ed6baa62f5adc98277e736fa223
 SHA512:
-  metadata.gz: 7691132899688d326b7014fd010a7887a107958e717ea1da66b7640fe2fb4b4ace845d0f6c5db23f483904ff13e00d19fe4510b69539a2b1ad91a0cf18c9a429
-  data.tar.gz: 7667b6be0f7ab4634020198f0e30566ea1b3338b79747017c3c7460e8910ca664bbf7222c41902f013d0a161e84481df09bf35b1e69c610ca34756e7c701b72a
+  metadata.gz: f97bf4428e04bfcb3fb018b76663b825ed46357419ec43ecd5bc2b3c5fe18463fcc8d9f42ecb6d26be59a43404f3d5fa04b1ee2c715983fa971b09c08318d1c5
+  data.tar.gz: cdc1be08b4f0ef9c13e93625c16be13fb35198fbd0ed2b9d222fc76cde0989b1fc456804aee2bf8a5cc7016ad3cf4c5304e74833638ed9f898b5a54704aa9c6b

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [0.3.0] — 2026-09-17
+
+### Added
+
+- **The table ships with the gem.** `db/migrate/create_ask_guest_sessions.rb` is
+  now the one definition of `ask_guest_sessions`, and the install generator copies
+  it into the host (`migration_template`, so it lands with a fresh timestamp
+  and is skipped if the host already has one). Re-running the installer after
+  an upgrade installs any migration a later version adds.
+- **The installer writes the whole app-side wiring:** the migration, the
+  `GuestSession` model, and `config/initializers/ask_guests.rb` — then prints
+  the controller, claim, and sweep steps. Nothing is left for the host to
+  transcribe from a README.
+- **`Ask::Guests::MissingTable`** — the ActiveRecord store checks for its table
+  on the first read or write (`#verify_schema!`) and raises this, naming the
+  file to copy, instead of surfacing a database error about a relation.
+- The README documents the non-Rails path (plain ActiveRecord/Sinatra) and why
+  the host owns the schema rather than the gem creating it at boot.
+
+### Changed
+
+- `Ask::Guests::ActiveRecord::SessionStore` raises on a missing table for
+  `#create`, `#find`, and `#sweep_stale`; `#verify_schema!` is public if a host
+  wants to check at boot.
+
+## [0.2.0] — 2026-09-16
+
+### Changed
+
+- **Budgets are now named categories instead of policy classes.** Replace
+  `config.policies = [Budget::TurnLimit.new(per_day: 40)]` with
+  `config.categories = {turns: {limit: 40, per: :day}}`. Each category is a
+  named limit with a period (`:day`, `:week`, `:month`) and optionally its
+  own usage key (`parses: {limit: 20, per: :day, usage_key: :uploads}`).
+  Any usage key is meterable — turns, tokens, uploads, messages, or your
+  own.
+- **New budget API:** `allowed?(subject, *categories)`, `remaining(subject,
+  :turns)`, `exceeded(subject)` (categories out of budget), `record!` with
+  keyword usage (`record!(session, turns: 1, tokens: 850)`).
+- `Budget::TurnLimit`, `Budget::TokenQuota`, `Budget::Unlimited`, and
+  `Budget::Policy` are gone; an empty category list means unlimited.
+
 ## [0.1.0] — 2026-09-15
 
 ### Added

data/README.md

@@ -11,7 +11,7 @@ Four concepts, one gem:
 |---|---|
 | **Identity** | A random session id behind an HMAC-signed token. No fake `User` rows, nothing to enumerate without the secret. |
 | **Ownership** | Hosts register claimable handlers; records owned by a guest carry its session id. |
-| **Metering** | Daily turn/token budgets (composable policies) with automatic rollover — bound anonymous AI spend. |
+| **Metering** | Named budget categories (`turns: 40/day`, `tokens: 10k/day`, `uploads: 5/day`, …) with automatic period rollover — bound anonymous AI spend. |
 | **Claim** | On sign-up/sign-in, transfer all guest records in one transaction, exactly once. |
 
 Plus retention: unclaimed sessions are swept after a configurable window.
@@ -31,14 +31,47 @@ require "ask-guests/rails"           # controller concern, auth hook, sweep job
 gem "ask-guests"
 ```
 
-In a Rails app, run the installer:
+### Rails
 
 ```bash
 bin/rails generate ask:guests:install
+bin/rails db:migrate
 ```
 
-It creates the `guest_sessions` migration and an initializer, and prints
-the model and controller wiring.
+The installer copies the `ask_guest_sessions` migration out of the gem, writes
+`app/models/guest_session.rb`, creates `config/initializers/ask_guests.rb`, and
+prints the controller wiring. Then register what claiming transfers (see
+[Claim](#claim)) and schedule the sweep (see [Retention](#retention)).
+
+The table ships with the gem (`db/migrate/create_ask_guest_sessions.rb`) rather
+than being created by it. Your app owns its schema: migrations run at deploy
+time, under review, against whichever database you point them at — a gem that
+creates tables at boot would need DDL rights at runtime, race other servers,
+and have to guess which database is yours. Re-running the installer after
+upgrading installs any migration a later version added, and skips the ones you
+already have.
+
+### Anywhere else (plain ActiveRecord, Sinatra, a script)
+
+The core needs nothing; the ActiveRecord adapter needs the table:
+
+```ruby
+require "ask-guests/active_record"
+
+class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+  self.table_name = "ask_guest_sessions"
+end
+
+Ask::Guests.configure do |config|
+  config.secret = ENV.fetch("GUEST_TOKEN_SECRET")
+  config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
+end
+```
+
+Copy `db/migrate/create_ask_guest_sessions.rb` from the gem into your migrations
+and run them however you migrate. If the table is missing, the store raises
+`Ask::Guests::MissingTable` at the first read or write — with the file to copy
+in the message — rather than letting the database complain about a relation.
 
 ## Core usage
 
@@ -46,7 +79,10 @@ the model and controller wiring.
 Ask::Guests.configure do |config|
   config.secret = ENV.fetch("GUEST_TOKEN_SECRET")
   config.store = Ask::Guests::Stores::Memory.new
-  config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+  config.categories = {
+    turns:  {limit: 40,     per: :day},
+    tokens: {limit: 10_000, per: :day}
+  }
   config.retention = 14 * 24 * 60 * 60 # seconds
 end
 
@@ -77,14 +113,26 @@ response = agent.run(prompt)
 budget.record!(guest_session, turns: 1, tokens: response.input_tokens + response.output_tokens)
 ```
 
-Policies compose — a guest is allowed only while every policy has budget
-left, and counters roll over daily with no scheduled work:
+Categories compose — a guest is allowed only while every category has
+budget left in its period, and counters roll over with no scheduled work.
+Periods are `:day`, `:week`, or `:month`; any usage key can be metered,
+including your own (uploads, parses, messages):
 
 ```ruby
-config.policies = [
-  Ask::Guests::Budget::TurnLimit.new(per_day: 40),
-  Ask::Guests::Budget::TokenQuota.new(per_day: 10_000)
-]
+config.categories = {
+  turns:    {limit: 40,     per: :day},
+  tokens:   {limit: 10_000, per: :day},
+  uploads:  {limit: 5,      per: :day},
+  messages: {limit: 100,    per: :month},
+  parses:   {limit: 20,     per: :day, usage_key: :uploads} # meter one key as another category
+}
+
+budget = Ask::Guests.budget
+budget.allowed?(guest)                    # all categories
+budget.allowed?(guest, :turns)            # one category
+budget.remaining(guest, :turns)           # => 12
+budget.exceeded(guest)                    # => [:tokens]
+budget.record!(guest, turns: 1, tokens: 850)
 ```
 
 ### Claiming on sign-up
@@ -113,7 +161,7 @@ Ask::Guests.sweep.call # destroys unclaimed sessions inactive past retention
 ```ruby
 # app/models/guest_session.rb
 class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-  self.table_name = "guest_sessions"
+  self.table_name = "ask_guest_sessions"
   has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
 end
 
@@ -121,7 +169,7 @@ end
 Ask::Guests.configure do |config|
   config.secret = Rails.application.secret_key_base
   config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
-  config.policies = [Ask::Guests::Budget::TurnLimit.new(per_day: 40)]
+  config.categories = {turns: {limit: 40, per: :day}}
 end
 ```
 

data/db/migrate/20260917120000_create_ask_guest_sessions.rb

@@ -0,0 +1,30 @@
+# The ask_guest_sessions table.
+#
+# Shipped with the gem so the table has one definition: the install generator
+# copies this file into a Rails app, and an app without Rails copies the same
+# body into whatever migrates its database. A host that edits its copy keeps
+# its own table — but the columns the store reads and writes are these.
+#
+# Named for the gem, like every other table this ecosystem ships: a host may
+# well have its own `guest_sessions`, and the gem has no business claiming it.
+#
+# `t.json` rather than `jsonb` so the same migration runs on PostgreSQL,
+# MySQL, and SQLite; nothing here queries inside the documents, so the jsonb
+# operators buy nothing. Stamped 7.1 because that is the oldest Active Record
+# the gem supports — a newer Rails runs it unchanged.
+class CreateAskGuestSessions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :ask_guest_sessions do |t|
+      t.json :counters, null: false, default: {}
+      t.json :metadata, null: false, default: {}
+      t.datetime :last_seen_at
+      t.datetime :converted_at
+      t.references :owner, polymorphic: true
+      t.timestamps
+    end
+
+    # Speculative: sessions at risk of being swept.
+    add_index :ask_guest_sessions, :converted_at
+    add_index :ask_guest_sessions, :last_seen_at
+  end
+end

data/lib/ask/guests/active_record/session_base.rb

@@ -8,7 +8,7 @@ module Ask
       # table created by the migration:
       #
       #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-      #     self.table_name = "guest_sessions"
+      #     self.table_name = "ask_guest_sessions"
       #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
       #   end
       #
@@ -22,6 +22,14 @@ module Ask
       class SessionBase < ::ActiveRecord::Base
         self.abstract_class = true
 
+        # The table is named for the gem, the way the rest of the ecosystem's
+        # tables are: a host may have its own `guest_sessions`. A subclass that
+        # says nothing lands on ask_guest_sessions rather than claiming the
+        # generic name; one that sets table_name itself keeps its own.
+        def self.table_name_prefix
+          "ask_"
+        end
+
         # The gem owns these columns' semantics; use the adapter-independent
         # JSON type so PostgreSQL json/jsonb and SQLite text columns behave
         # identically (and the model loads without a database connection).

data/lib/ask/guests/active_record/session_store.rb

@@ -6,7 +6,7 @@ module Ask
       # ActiveRecord-backed session store.
       #
       #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-      #     self.table_name = "guest_sessions"
+      #     self.table_name = "ask_guest_sessions"
       #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
       #   end
       #
@@ -26,6 +26,7 @@ module Ask
         end
 
         def create(attributes = {})
+          verify_schema!
           attributes = attributes.to_h.transform_keys(&:to_sym)
           now = Guests.configuration.now
           record = model.new(
@@ -42,6 +43,7 @@ module Ask
         def find(id)
           return nil if id.nil?
 
+          verify_schema!
           model.find_by(id: id)&.to_guest_session
         end
 
@@ -69,6 +71,7 @@ module Ask
         end
 
         def sweep_stale(before:)
+          verify_schema!
           destroyed = 0
           stale_scope(before).find_each do |record|
             record.destroy
@@ -77,6 +80,16 @@ module Ask
           destroyed
         end
 
+        # Raises MissingTable unless the sessions table is there. Called by the
+        # operations a host reaches first, so a forgotten migration names
+        # itself instead of surfacing as a database error about a relation.
+        # Idempotent and cheap: Active Record caches the schema.
+        def verify_schema!
+          return true if model.table_exists?
+
+          raise MissingTable, model.table_name
+        end
+
         def transaction(&block)
           model.transaction(&block)
         end

data/lib/ask/guests/budget/category.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ask
+  module Guests
+    class Budget
+      # A named budget line: a limit on one usage category per period.
+      #
+      #   Category.new(:turns,   limit: 40,     per: :day)
+      #   Category.new(:tokens,  limit: 10_000, per: :day)
+      #   Category.new(:uploads, limit: 5,      per: :day)
+      #   Category.new(:messages, limit: 100,   per: :month)
+      #
+      # Usage is recorded by keyword and consumed by the category with the
+      # same name:
+      #
+      #   budget.record!(session, turns: 1, tokens: 850, uploads: 1)
+      #
+      # A category may meter a different usage key with +usage_key+ (for
+      # example, counting "parses" while the call site reports uploads).
+      #
+      # Counters live on the subject and store a period bucket alongside
+      # the count ("day" resets at midnight UTC, "week" on ISO weeks,
+      # "month" on calendar months), so rollover is automatic and needs no
+      # scheduled work.
+      class Category
+        PERIODS = %i[day week month].freeze
+
+        attr_reader :name, :limit, :period, :usage_key
+
+        def initialize(name, limit:, per: :day, usage_key: nil)
+          @name = name.to_sym
+          @limit = limit.to_i
+          @period = per.to_sym
+          @usage_key = (usage_key || name).to_sym
+
+          unless PERIODS.include?(@period)
+            raise ArgumentError, "unknown period #{per.inspect} (expected one of #{PERIODS.inspect})"
+          end
+        end
+
+        # @return [Integer] how much this usage costs the category
+        def amount_for(usage)
+          usage.fetch(@usage_key, 0).to_i
+        end
+
+        # @return [Integer] remaining budget for the current period
+        def remaining(subject, time)
+          value = subject.counter_value(counter_key, bucket(time))
+          [@limit - value, 0].max
+        end
+
+        def exceeded?(subject, time)
+          remaining(subject, time).zero?
+        end
+
+        # Records usage on the subject (without persisting — the budget
+        # persists through the store).
+        def record!(subject, usage, time)
+          amount = amount_for(usage)
+          return subject if amount.zero?
+
+          count = subject.counter_value(counter_key, bucket(time)) + amount
+          subject.set_counter!(counter_key, count, bucket(time))
+        end
+
+        # Counter name on the subject.
+        def counter_key
+          @name.to_s
+        end
+
+        # Period bucket key for +time+; a different bucket reads as zero.
+        def bucket(time)
+          utc = time.utc
+          case @period
+          when :day then utc.strftime("%Y-%m-%d")
+          when :week then utc.strftime("%G-W%V")
+          when :month then utc.strftime("%Y-%m")
+          end
+        end
+
+        def to_h
+          {name: name, limit: limit, period: period, usage_key: usage_key}
+        end
+      end
+    end
+  end
+end

data/lib/ask/guests/budget.rb

@@ -2,66 +2,104 @@
 
 module Ask
   module Guests
-    # Meters guest usage against one or more policies and records usage
-    # afterwards. Policies are checked collectively: a guest is allowed only
-    # while every policy has budget remaining.
+    # Meters usage against named category budgets and records usage
+    # afterwards. Categories are checked collectively: a subject is allowed
+    # only while every category has budget remaining in its period.
     #
     #   budget = Ask::Guests.budget
-    #   budget.allowed?(session) # => true/false
-    #   budget.remaining(session) # => Integer (minimum across policies)
+    #   budget.allowed?(session)                 # => true/false
+    #   budget.allowed?(session, :turns)         # => one category
+    #   budget.remaining(session, :turns)        # => 12
+    #   budget.exceeded(session)                 # => [:tokens]
     #   budget.record!(session, turns: 1, tokens: 850)
     #
-    # Counters live on the session and roll over daily, so "per day" limits
+    # Counters live on the subject and roll over per period, so limits
     # reset without any scheduled work.
     class Budget
-      attr_reader :policies, :store
+      attr_reader :categories, :store
 
-      def initialize(policies: nil, store: Guests.store, clock: Guests.configuration.clock)
-        @policies = normalize(policies)
+      # @param categories [Array<Category>, Hash, nil] Category objects or
+      #   a hash of +name => {limit:, per:, usage_key:}+. Empty/nil means
+      #   unlimited.
+      def initialize(categories: nil, store: Guests.store, clock: Guests.configuration.clock)
+        @categories = normalize(categories)
         @store = store
         @clock = clock
       end
 
-      # @return [Boolean] true while every policy has budget left
-      def allowed?(session)
-        return true if session.nil?
+      # @param names [Array<Symbol>] restrict the check to these categories
+      # @return [Boolean] true while every checked category has budget left
+      def allowed?(subject, *names)
+        return true if subject.nil?
 
-        policies.all? { |policy| policy.remaining(session, today) > 0 }
+        selected(names).all? { |category| category.remaining(subject, now) > 0 }
       end
 
-      # Minimum remaining budget across policies (Float::INFINITY when no
-      # policy limits usage).
-      def remaining(session)
-        return Float::INFINITY if session.nil?
+      # Remaining budget for one category, or the minimum across all
+      # categories (Float::INFINITY when unlimited).
+      def remaining(subject, name = nil)
+        return Float::INFINITY if subject.nil?
 
-        policies.map { |policy| policy.remaining(session, today) }.min
+        if name
+          category(name).remaining(subject, now)
+        else
+          categories.map { |category| category.remaining(subject, now) }.min || Float::INFINITY
+        end
+      end
+
+      # @return [Array<Symbol>] categories with no budget left this period
+      def exceeded(subject)
+        return [] if subject.nil?
+
+        categories.select { |category| category.exceeded?(subject, now) }.map(&:name)
       end
 
-      # Records usage, persists the session through the store, and returns it.
-      def record!(session, turns: 0, tokens: 0)
-        return session if session.nil?
+      # Records usage, persists the subject through the store, and returns
+      # it. Usage is keyed by category name (or the category's usage_key):
+      #
+      #   budget.record!(session, turns: 1, tokens: 850, uploads: 2)
+      def record!(subject, **usage)
+        return subject if subject.nil?
 
-        policies.each { |policy| policy.record!(session, turns: turns, tokens: tokens, today: today) }
-        store.update(session)
-        session
+        categories.each { |category| category.record!(subject, usage, now) }
+        store.update(subject)
+        subject
       end
 
       def unlimited?
-        policies.all? { |policy| policy.remaining(Session.new(id: "probe"), today) == Float::INFINITY }
+        categories.empty?
+      end
+
+      # @return [Category]
+      def category(name)
+        categories.find { |category| category.name == name.to_sym } ||
+          raise(ArgumentError, "unknown budget category #{name.inspect}")
       end
 
       private
 
-      def normalize(policies)
-        case policies
-        when nil then [Budget::Unlimited.new]
-        when Array then policies
-        else [policies]
-        end
+      def selected(names)
+        return categories if names.nil? || names.empty?
+
+        names.map { |name| category(name) }
+      end
+
+      def now
+        @clock.call
+      end
+
+      def normalize(categories)
+        case categories
+        when nil then []
+        when Hash then categories.flat_map { |name, options| build(name, options) }
+        when Array then categories.flat_map { |entry| entry.is_a?(Hash) ? normalize(entry) : [entry] }
+        else [categories]
+        end.map { |entry| entry.is_a?(Category) ? entry : build(entry, {}) }
       end
 
-      def today
-        @clock.call.utc.strftime("%Y-%m-%d")
+      def build(name, options)
+        options = options.to_h.transform_keys(&:to_sym)
+        [Category.new(name, **options)]
       end
     end
   end

data/lib/ask/guests/errors.rb

@@ -11,5 +11,24 @@ module Ask
         super
       end
     end
+
+    # Raised on the first store operation when the sessions table is not
+    # there. The gem ships the table, so a host that has not installed it
+    # should hear that — and the command that fixes it — rather than a
+    # database complaining about a relation nobody mentioned.
+    class MissingTable < Error
+      def initialize(table_name = "ask_guest_sessions")
+        super(<<~MESSAGE.strip)
+          The #{table_name} table does not exist.
+
+          Install the table the gem ships, then migrate:
+            bin/rails generate ask:guests:install
+            bin/rails db:migrate
+
+          Without Rails, copy db/migrate/*_create_ask_guest_sessions.rb from the gem
+          into your migrations and run them.
+        MESSAGE
+      end
+    end
   end
 end

data/lib/ask/guests/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Guests
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/ask/guests.rb

@@ -7,10 +7,7 @@ require_relative "guests/session"
 require_relative "guests/stores/base"
 require_relative "guests/stores/memory"
 require_relative "guests/budget"
-require_relative "guests/budget/policy"
-require_relative "guests/budget/unlimited"
-require_relative "guests/budget/turn_limit"
-require_relative "guests/budget/token_quota"
+require_relative "guests/budget/category"
 require_relative "guests/claim"
 require_relative "guests/sweep"
 
@@ -79,7 +76,7 @@ module Ask
       # so configuration changes (and test resets) always take effect.
       def budget
         Budget.new(
-          policies: configuration.policies,
+          categories: configuration.categories,
           store: configuration.store,
           clock: configuration.clock
         )
@@ -121,8 +118,8 @@ module Ask
       attr_accessor :secret
       # Persistence adapter (see Stores::Base). Defaults to in-memory.
       attr_accessor :store
-      # Usage policies (see Budget::TurnLimit, Budget::TokenQuota).
-      attr_accessor :policies
+      # Budget categories (see Budget::Category): named limits per period.
+      attr_accessor :categories
       # Unclaimed sessions older than this many seconds are swept.
       attr_accessor :retention
       # Injectable clock returning a Time (used for daily counter rollover
@@ -141,7 +138,7 @@ module Ask
       def initialize
         @secret = nil
         @store = Stores::Memory.new
-        @policies = [Budget::Unlimited.new]
+        @categories = []
         @retention = 14 * 24 * 60 * 60
         @clock = -> { Time.now.utc }
         @cookie_name = "guest_session_token"

data/lib/generators/ask/guests/install/install_generator.rb

@@ -1,65 +1,124 @@
 # frozen_string_literal: true
 
 require "rails/generators"
+require "rails/generators/migration"
 
 module Ask
   module Guests
     module Generators
+      # Installs ask-guests into a Rails app: the ask_guest_sessions migration, the
+      # model that maps it, and an initializer to configure. Run it once, then
+      # edit what it wrote.
+      #
       #   bin/rails generate ask:guests:install
+      #
+      # The migrations are copied from the gem's own db/migrate, so the table
+      # has one definition — the one the store expects. A host that already
+      # migrated ask_guest_sessions keeps its file: an identical name is skipped
+      # rather than duplicated. Re-running the installer after an upgrade is
+      # how a host picks up a migration a later version added.
       class InstallGenerator < ::Rails::Generators::Base
+        include Rails::Generators::Migration
+
         source_root File.expand_path("templates", __dir__)
+        # The DDL lives in the gem's db/migrate, not in a second copy here.
+        source_paths << File.expand_path("../../../../../db/migrate", __dir__)
+
+        desc "Creates the ask_guest_sessions migration, the model, and the ask-guests initializer"
+
+        def self.next_migration_number(_dir)
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        end
+
+        # The migrations the gem ships, by file name.
+        def self.migrations
+          Dir[File.expand_path("../../../../../db/migrate/*.rb", __dir__)]
+            .map { |path| File.basename(path) }.sort
+        end
+
+        def create_migrations
+          self.class.migrations.each do |migration|
+            next if installed?(migration) && !options[:force]
 
-        desc "Creates the guest_sessions migration and ask-guests initializer"
+            migration_template migration, "db/migrate/#{migration.sub(/\A\d+_/, "")}"
+          end
+        end
+
+        def create_model
+          template "guest_session.rb", "app/models/guest_session.rb"
+        end
 
         def create_initializer
           template "initializer.rb", "config/initializers/ask_guests.rb"
         end
 
-        def create_migration
-          timestamp = Time.now.utc.strftime("%Y%m%d%H%M%S")
-          template "migration.rb", "db/migrate/#{timestamp}_create_guest_sessions.rb"
+        def check_schema
+          if schema_installed?
+            say "ask_guest_sessions is in place.", :green
+          else
+            say "Run bin/rails db:migrate to create ask_guest_sessions.", :yellow
+          end
         end
 
-        def show_readme
+        def show_next_steps
           say <<~MESSAGE
 
             ask-guests installed.
 
             Next steps:
 
-            1. Define the model (app/models/guest_session.rb):
+            1. Register what claiming transfers — one handler per record a
+               visitor owns (config/initializers/ask_guests.rb):
 
-                 class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-                   self.table_name = "guest_sessions"
-
-                   # Destroying a session sweeps everything the guest owned:
-                   # has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
+                 Ask::Guests.claimable(:chats) do |session, owner|
+                   Chat.where(guest_session_id: session.id)
+                     .update_all(user_id: owner.id, guest_session_id: nil)
                  end
 
-            2. Register what claiming transfers (config/initializers/ask_guests.rb).
-
-            3. Allow guests in a controller:
+            2. Let guests in, in the controller that serves them:
 
                  include Ask::Guests::Rails::Controller
+
                  allow_guest_access
-                 before_action :require_visitor
+                 before_action :require_visitor, only: %i[chat create]
 
-            4. Claim on authentication (Devise example):
+               ...and key their records to #current_guest_session.
+
+            3. Claim on authentication (Devise example):
 
                  include Ask::Guests::Rails::ClaimOnAuthentication
                  after_action :claim_guest_session, only: :create
 
-                 def guest_claim_owner = current_user.account_users.first
+                 def guest_claim_owner = current_user
 
-            5. Schedule the sweep:
+            4. Sweep abandoned sessions on a schedule (config/recurring.yml
+               with Solid Queue):
 
-                 production:
-                   guests_sweep:
-                     class: "Ask::Guests::Rails::SweepJob"
-                     schedule: every day at 4am
+                 sweep_guest_sessions:
+                   command: "Ask::Guests::Rails::SweepJob.perform_now"
+                   schedule: every day at 4am
 
           MESSAGE
         end
+
+        private
+
+        # A migration the host already has is the host's — it may have run
+        # already, so the gem does not touch it unless asked with --force.
+        def installed?(migration)
+          name = migration.sub(/\A\d+_/, "").delete_suffix(".rb")
+          self.class.migration_exists?(File.join(destination_root, "db/migrate"), name)
+        end
+
+        # Advisory only: a database that is not there yet (db:create has not
+        # run, or the app boots without one) is not this generator's problem.
+        def schema_installed?
+          return false unless defined?(::ActiveRecord::Base)
+
+          ::ActiveRecord::Base.connection.table_exists?("ask_guest_sessions")
+        rescue ::ActiveRecord::ActiveRecordError
+          false
+        end
       end
     end
   end

data/lib/generators/ask/guests/install/templates/guest_session.rb

@@ -0,0 +1,16 @@
+require "ask-guests/active_record"
+
+# The ask_guest_sessions table, as the store reads and writes it.
+#
+# Nothing about a guest is a User row: a visitor is their own record, which is
+# what lets an abandoned visit be swept and a visitor who signs up keep the
+# threads they already had.
+class GuestSession < Ask::Guests::ActiveRecord::SessionBase
+  self.table_name = "ask_guest_sessions"
+
+  # Everything a guest owns hangs off this row, so sweeping an abandoned
+  # session takes those records with it. Add one line per model that carries a
+  # guest_session_id — and make sure claiming moves them (see the initializer):
+  #
+  #   has_many :chats, foreign_key: :guest_session_id, dependent: :destroy
+end

data/lib/generators/ask/guests/install/templates/initializer.rb

@@ -1,39 +1,46 @@
-# frozen_string_literal: true
+require "ask-guests/active_record"
+# The controller concern and the sweep job ride with Rails; the store is
+# ActiveRecord's.
+require "ask-guests/rails"
 
-# Guest access configuration (ask-guests).
+# Guest access (ask-guests).
 #
-# Anonymous visitors get a signed-cookie session, metered agent usage, and
-# a single-use claim that moves everything they own to a real account when
-# they sign up. See https://github.com/ask-rb/ask-guests for the full guide.
+# Anonymous visitors get a signed-cookie session, metered AI usage, and a
+# single-use claim that moves everything they own to a real account when they
+# sign up. See https://github.com/ask-rb/ask-guests for the full guide.
+#
+# Configured on prepare rather than at boot: the store holds the model class,
+# and a reload must not leave it holding the class that was replaced.
+Rails.application.config.to_prepare do
+  Ask::Guests.configure do |config|
+    # Required: HMAC secret for guest tokens. Rotating it invalidates all
+    # outstanding guest cookies (they simply start fresh).
+    config.secret = Rails.application.secret_key_base
 
-Ask::Guests.configure do |config|
-  # Required: HMAC secret for guest tokens. Rotating it invalidates all
-  # outstanding guest cookies (they simply start fresh).
-  config.secret = Rails.application.secret_key_base
+    # Persistence: the model the install generator wrote over the migration.
+    config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
 
-  # Persistence. Define the model first (see the install generator output):
-  #
-  #   class GuestSession < Ask::Guests::ActiveRecord::SessionBase
-  #     self.table_name = "guest_sessions"
-  #     has_many :work_requests, foreign_key: :guest_session_id, dependent: :destroy
-  #   end
-  config.store = Ask::Guests::ActiveRecord::SessionStore.new(model: GuestSession)
+    # Usage caps for anonymous visitors, one entry per category. Signing up
+    # lifts them because a signed-in request never touches the guest budget.
+    # Periods are :day, :week, or :month; counters roll over automatically.
+    # Empty means unlimited — appropriate when the host bills the visit some
+    # other way, and a cap needs a state to show the visitor when it bites.
+    config.categories = {
+      turns: {limit: 40, per: :day}
+      # tokens:  {limit: 10_000, per: :day},
+      # uploads: {limit: 5,      per: :day},
+      # messages: {limit: 100,   per: :month}
+    }
 
-  # Usage caps for anonymous visitors. Signing up lifts them because a
-  # signed-in request never touches the guest budget.
-  config.policies = [
-    Ask::Guests::Budget::TurnLimit.new(per_day: 40)
-    # Ask::Guests::Budget::TokenQuota.new(per_day: 10_000)
-  ]
-
-  # Unclaimed sessions inactive for this long are swept (seconds).
-  config.retention = 14 * 24 * 60 * 60
+    # Unclaimed sessions inactive for this long are swept (seconds).
+    config.retention = 14 * 24 * 60 * 60
+  end
 
   # What claiming transfers. Register one handler per owned model; they run
   # inside the claim's transaction, exactly once.
   #
-  # Ask::Guests.claimable(:work_requests) do |session, owner|
-  #   WorkRequest.where(guest_session_id: session.id)
-  #     .update_all(account_id: owner.account_id, account_user_id: owner.id, guest_session_id: nil)
-  # end
+  #   Ask::Guests.claimable(:work_requests) do |session, owner|
+  #     WorkRequest.where(guest_session_id: session.id)
+  #       .update_all(account_id: owner.account_id, account_user_id: owner.id, guest_session_id: nil)
+  #   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-guests
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -93,6 +93,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 description: 'Give anonymous visitors a durable identity with metered AI access: signed
   guest sessions, per-day turn/token budgets, single-use claiming of records into
   a real owner on sign-up, and stale-session retention. Framework-agnostic core with
@@ -106,6 +120,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- db/migrate/20260917120000_create_ask_guest_sessions.rb
 - lib/ask-guests.rb
 - lib/ask-guests/active_record.rb
 - lib/ask-guests/rails.rb
@@ -114,10 +129,7 @@ files:
 - lib/ask/guests/active_record/session_base.rb
 - lib/ask/guests/active_record/session_store.rb
 - lib/ask/guests/budget.rb
-- lib/ask/guests/budget/policy.rb
-- lib/ask/guests/budget/token_quota.rb
-- lib/ask/guests/budget/turn_limit.rb
-- lib/ask/guests/budget/unlimited.rb
+- lib/ask/guests/budget/category.rb
 - lib/ask/guests/claim.rb
 - lib/ask/guests/errors.rb
 - lib/ask/guests/rails/claim_on_authentication.rb
@@ -130,8 +142,8 @@ files:
 - lib/ask/guests/token.rb
 - lib/ask/guests/version.rb
 - lib/generators/ask/guests/install/install_generator.rb
+- lib/generators/ask/guests/install/templates/guest_session.rb
 - lib/generators/ask/guests/install/templates/initializer.rb
-- lib/generators/ask/guests/install/templates/migration.rb
 homepage: https://github.com/ask-rb/ask-guests
 licenses:
 - MIT

data/lib/ask/guests/budget/policy.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # Base class for usage policies. A policy owns one counter key (for
-      # example "turns" or "tokens") and a daily limit for it.
-      #
-      # Subclasses implement +counter_key+, +limit+, and +amount_for+.
-      class Policy
-        # @return [String] counter name on the session
-        def counter_key
-          raise NotImplementedError
-        end
-
-        # @return [Integer, Float::INFINITY] daily limit
-        def limit
-          raise NotImplementedError
-        end
-
-        # @return [Integer] how much this usage costs in counter units
-        def amount_for(turns:, tokens:)
-          raise NotImplementedError
-        end
-
-        # @return [Integer, Float] remaining budget for today
-        def remaining(session, today)
-          value = session.counter_value(counter_key, today)
-          [limit - value, 0].max
-        end
-
-        def record!(session, turns:, tokens:, today:)
-          amount = amount_for(turns: turns, tokens: tokens)
-          return session if amount.to_i.zero?
-
-          count = session.counter_value(counter_key, today) + amount.to_i
-          session.set_counter!(counter_key, count, today)
-        end
-      end
-    end
-  end
-end

data/lib/ask/guests/budget/token_quota.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # Limits tokens per day, for apps that meter actual consumption
-      # (input + output tokens) instead of turns.
-      #
-      #   Budget::TokenQuota.new(per_day: 10_000)
-      class TokenQuota < Policy
-        attr_reader :per_day
-
-        def initialize(per_day:)
-          super()
-          @per_day = per_day.to_i
-        end
-
-        def counter_key = "tokens"
-        def limit = per_day
-        def amount_for(turns:, tokens:) = tokens
-      end
-    end
-  end
-end

data/lib/ask/guests/budget/turn_limit.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # Limits agent turns per day. One "turn" is one agent run — the unit
-      # Kawibot meters.
-      #
-      #   Budget::TurnLimit.new(per_day: 40)
-      class TurnLimit < Policy
-        attr_reader :per_day
-
-        def initialize(per_day:)
-          super()
-          @per_day = per_day.to_i
-        end
-
-        def counter_key = "turns"
-        def limit = per_day
-        def amount_for(turns:, tokens:) = turns
-      end
-    end
-  end
-end

data/lib/ask/guests/budget/unlimited.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Ask
-  module Guests
-    class Budget
-      # No limits — the default policy. Useful for development and for apps
-      # that meter elsewhere.
-      class Unlimited < Policy
-        def counter_key = "unlimited"
-        def limit = Float::INFINITY
-        def amount_for(turns:, tokens:) = 0
-        def remaining(session, today) = Float::INFINITY
-      end
-    end
-  end
-end

data/lib/generators/ask/guests/install/templates/migration.rb

@@ -1,16 +0,0 @@
-class CreateGuestSessions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    create_table :guest_sessions do |t|
-      t.jsonb :counters, null: false, default: {}
-      t.jsonb :metadata, null: false, default: {}
-      t.datetime :last_seen_at
-      t.datetime :converted_at
-      t.references :owner, polymorphic: true
-      t.timestamps
-    end
-
-    # Speculative: sessions at risk of being swept.
-    add_index :guest_sessions, :converted_at
-    add_index :guest_sessions, :last_seen_at
-  end
-end