sponsored_logs 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fb5cc1d702c7a78769eabc68497519929f3b539022e060e183236bea09bf2e9
-  data.tar.gz: 833fc7655dc58fe08d225c30d8cbeb4fb671f8420e28174a902a2b90127a8126
+  metadata.gz: 71c5f68d3e16d9f70a3bbf6d1fddf4eb43be5f4d4e02aca424164644e2c15805
+  data.tar.gz: 6c966d77ed2ac1161dee7d0128ac4b4876b6b71dc6de70d2ba4ae01a64743851
 SHA512:
-  metadata.gz: a082ca74275c9295fbe89b5a37df6ff53ef4384be302b6fe63a6b69f93ee11ec9ac2443a75375ea3a2fb78db96fb2285a825d797c0d793af7834b64304d28faf
-  data.tar.gz: 0e583c888d9b72d785d76492c1dc7b71cebb6769321f025a2d9a3282a5ff0425f51dfbbbca693a6e1382bc0dbbe19eb3a4bc71c3825535e8e46444fbebc00ba0
+  metadata.gz: f5ac2e5b839c73b285125a4a6b739ec47c085e70ee00c63fe880a16970b94bdace3588411ec9d46470ca9c8fc0414331e47bcb36fc8cdf3c94653bf190ff2df9
+  data.tar.gz: 5eca7cfa43eebb905ecd905b9c9664cbd1dac4d15a03ff7afb40320c515370375befdbaa461aead4f128a204809f67753e2df35302693d65382a3570cc9b33ff

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-10
+
+### Added
+
+- **Identity is a moat.** Copy is a draft, not an account — an advertiser that rewrites its line is not a new advertiser. Every ad takes an optional `id`; set it and impressions, spend, and cap ride through a mid-flight rewrite, omit it and `id` falls back to a content hash of the text so nothing already booked moves. Two advertisers can even run the same line as separate books. Works in the JSON ads file
+
+### Changed
+
+- **The ledger settles by account, not by copy.** The store snapshot is now `{ id => {text:, impressions:, cpm:} }` — text rides along as a label so the Command Center still reads in plain English, but caps and reporting key on `id` end to end. Custom stores must return the new shape
+- **`text_digest` retires; `ad_id` takes the desk.** The ActiveRecord ledger keys on `ad_id`, which for a no-id ad is exactly the old text digest, so existing rows line up untouched. Existing installs rerun `rails g sponsored_logs:install` (or rename the column and its unique index). The Redis store keys on `id` too, so existing Redis tallies reset once on upgrade
+
 ## [0.3.1] - 2026-09-10
 
 ### Fixed
@@ -78,7 +89,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Requires Ruby >= 3.1
 
-[Unreleased]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.1.0...v0.2.0

data/README.md

@@ -233,6 +233,26 @@ A missing `weight` defaults to `1`; a negative weight is treated as `0`. A
 missing `cpm` defaults to `0`. A pool that is empty, has only blank text, or
 sums to zero weight falls back to the built-in list.
 
+### 🪪 Stable ad identity (portfolio continuity)
+
+Copy is not identity — copy is a draft. An advertiser that rewrites its line is
+not a new account, and two advertisers that happen to write the same line are
+not one. Give each creative a stable `id` and its impressions, spend, and cap
+carry across every rewrite:
+
+```ruby
+SponsoredLogs.sponsor!(ads: [
+  { id: "acme-q3", text: "Acme: now with more Acme.", weight: 1, cap: 10_000 },
+  { id: "acme-q3", text: "Acme: even MORE Acme.",     weight: 1, cap: 10_000 } # same account, new copy
+])
+```
+
+Omit `id` and it defaults to a content hash of the text — exactly how the ledger
+has always keyed — so nothing already in flight moves. `id` works in the JSON
+ads file too. Tallies, cap governance, and the Command Center all settle by
+account, then read your copy back in plain English. **An advertiser should never
+have to re-earn its own history just to fix a typo.**
+
 ### 🗓️ Flighting (start and end dates)
 
 **Campaign flighting** — table stakes for any serious ad server, and we deliver

data/lib/generators/sponsored_logs/templates/create_sponsored_logs_impressions.rb.tt

@@ -3,7 +3,7 @@
 class CreateSponsoredLogsImpressions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
   def change
     create_table :sponsored_logs_impressions do |t|
-      t.string  :text_digest, null: false
+      t.string  :ad_id,       null: false
       t.text    :text,        null: false
       t.integer :impressions, null: false, default: 0
       t.float   :cpm,         null: false, default: 0.0
@@ -11,6 +11,6 @@ class CreateSponsoredLogsImpressions < ActiveRecord::Migration[<%= ActiveRecord:
       t.timestamps
     end
 
-    add_index :sponsored_logs_impressions, :text_digest, unique: true
+    add_index :sponsored_logs_impressions, :ad_id, unique: true
   end
 end

data/lib/sponsored_logs/advertisers.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "time"
+require "digest"
 
 module SponsoredLogs
   module Advertisers
@@ -73,6 +74,7 @@ module SponsoredLogs
       return if text.empty?
 
       {
+        id: Identity.coerce_id(fetch(entry, :id), text),
         advertiser: coerce_advertiser(fetch(entry, :advertiser)),
         text: text,
         weight: coerce_number(fetch(entry, :weight), default: 1.0),
@@ -197,7 +199,7 @@ module SponsoredLogs
 
     # Pick one normalized ad entry using the given selection mode, considering
     # only ads eligible at `now` -- live within their flight window and under
-    # their impression cap (counts is a text => impressions map). In :cpm mode
+    # their impression cap (counts is an id => impressions map). In :cpm mode
     # the cpm drives the odds; if every eligible cpm is 0 we fall back to manual
     # weights so selection never stalls.
     #
@@ -233,11 +235,12 @@ module SponsoredLogs
       house_ads? ? DEFAULT_ADS : PAID_ADS
     end
 
-    # Texts that identify house inventory, used to exclude house ads from
+    # Ids that identify house inventory, used to exclude house ads from
     # selection when the toggle is off (they can arrive via a user-supplied
-    # DEFAULT_ADS pool, not just the fallback).
+    # DEFAULT_ADS pool, not just the fallback). Keyed by id, not text, so
+    # editing house-ad copy can't break the match.
     #
-    HOUSE_TEXTS = HOUSE_ADS.map { |ad| ad[:text] }.freeze
+    HOUSE_IDS = HOUSE_ADS.map { |ad| Digest::SHA256.hexdigest(ad[:text]) }.freeze
 
     # Strip house creatives from a pool when the house_ads toggle is off; a
     # no-op when it is on. Keeps house ads out of rotation everywhere, not just
@@ -246,7 +249,7 @@ module SponsoredLogs
     def self.drop_house(pool)
       return pool if house_ads?
 
-      pool.reject { |ad| HOUSE_TEXTS.include?(ad[:text]) }
+      pool.reject { |ad| HOUSE_IDS.include?(Identity.id_for(ad)) }
     end
 
     # Whether the self-sponsoring house-ad inventory is enabled. Defaults to on
@@ -262,7 +265,7 @@ module SponsoredLogs
     end
 
     def self.eligible(pool, now, counts)
-      pool.select { |ad| eligible?(ad, now, counts[ad[:text]].to_i) }
+      pool.select { |ad| eligible?(ad, now, counts[Identity.id_for(ad)].to_i) }
     end
 
     # Render a normalized ad. :text ads (the default) stay byte-identical to

data/lib/sponsored_logs/identity.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module SponsoredLogs
+  # Stable ad identity. The ledger keys impressions on an ad's id, not its
+  # mutable text, so identical copy under different ids tallies separately and
+  # editing copy never resets a count. An absent/blank id falls back to
+  # SHA256(text), which is byte-compatible with the pre-0.4.0 text-keyed
+  # behavior and lines up with the ActiveRecord digest for zero-migration
+  # back-compat.
+  #
+  module Identity
+    module_function
+
+    # Resolve an explicit id (opt-in stability) or fall back to SHA256(text).
+    #
+    def coerce_id(value, text)
+      id = value.to_s.strip
+      id.empty? ? Digest::SHA256.hexdigest(text) : id
+    end
+
+    # The ledger key for an ad hash. Normalized ads carry :id; raw hashes
+    # recorded straight to a store fall back to the same SHA256(text) default,
+    # so both paths agree on identity. Accepts symbol- or string-keyed hashes.
+    #
+    def id_for(ad)
+      value = ad[:id] || ad["id"]
+      coerce_id(value, sanitize_text(ad[:text] || ad["text"]))
+    end
+
+    # Mirror Advertisers.sanitize_text so an id derived from raw text matches
+    # the id derived from normalized (sanitized) text for the same creative.
+    #
+    def sanitize_text(value)
+      value.to_s.gsub(Advertisers::CONTROL_CHARS, " ").strip
+    end
+  end
+end

data/lib/sponsored_logs/ledger/report.rb

@@ -7,7 +7,7 @@ module SponsoredLogs
     # Spend for an ad is impressions / 1000.0 * cpm (cost per mille).
     #
     class Report
-      Entry = Struct.new(:text, :impressions, :cpm, :spend, keyword_init: true)
+      Entry = Struct.new(:id, :text, :impressions, :cpm, :spend, keyword_init: true)
 
       def initialize(store)
         @store = store
@@ -18,17 +18,18 @@ module SponsoredLogs
       end
 
       def total_impressions
-        @store.snapshot.sum { |_text, data| data[:impressions] }
+        @store.snapshot.sum { |_id, data| data[:impressions] }
       end
 
       def total_spend
-        @store.snapshot.sum { |_text, data| spend_for(data[:impressions], data[:cpm]) }
+        @store.snapshot.sum { |_id, data| spend_for(data[:impressions], data[:cpm]) }
       end
 
       def entries
-        @store.snapshot.map do |text, data|
+        @store.snapshot.map do |id, data|
           Entry.new(
-            text: text,
+            id: id,
+            text: data[:text],
             impressions: data[:impressions],
             cpm: data[:cpm].to_f,
             spend: spend_for(data[:impressions], data[:cpm])
@@ -36,7 +37,7 @@ module SponsoredLogs
         end
       end
 
-      # Map of ad text => recorded impressions, for cap enforcement.
+      # Map of ad id => recorded impressions, for cap enforcement.
       #
       def impression_counts
         @store.snapshot.transform_values { |data| data[:impressions] }

data/lib/sponsored_logs/ledger/store/active_record.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require "digest"
-
 module SponsoredLogs
   module Ledger
     module Store
-      # Persistent store backed by ActiveRecord, one row per ad keyed by a
-      # SHA256 digest of the ad text (the full text is stored alongside for
-      # reporting). Rows live in `sponsored_logs_impressions`; run the
+      # Persistent store backed by ActiveRecord, one row per ad keyed by the
+      # stable ad id (the full text is stored alongside for reporting). For an
+      # ad with no explicit id the id defaults to SHA256(text), so the ad_id
+      # column holds exactly the digest the pre-0.4.0 text_digest column did.
+      # Rows live in `sponsored_logs_impressions`; run the
       # `sponsored_logs:install` generator to create the migration.
       #
       # ActiveRecord is required lazily, so it stays an optional dependency.
@@ -20,24 +20,25 @@ module SponsoredLogs
         end
 
         def record(ad)
-          digest = digest_for(ad[:text])
+          id = Identity.id_for(ad)
 
           # insert skips on conflict (INSERT ... ON CONFLICT DO NOTHING), so an
           # existing row keeps its impression count. Then atomically bump the
-          # counter and refresh cpm in a single UPDATE.
+          # counter and refresh cpm and text in a single UPDATE, so a stable id
+          # whose copy was edited shows the latest text (like the other stores).
           #
           @model.insert(
-            { text_digest: digest, text: ad[:text], cpm: ad[:cpm].to_f, impressions: 0 },
-            unique_by: :text_digest
+            { ad_id: id, text: ad[:text], cpm: ad[:cpm].to_f, impressions: 0 },
+            unique_by: :ad_id
           )
-          @model.where(text_digest: digest).update_all(
-            ["impressions = impressions + 1, cpm = ?", ad[:cpm].to_f]
+          @model.where(ad_id: id).update_all(
+            ["impressions = impressions + 1, cpm = ?, text = ?", ad[:cpm].to_f, ad[:text].to_s]
           )
         end
 
         def snapshot
           @model.all.to_h do |row|
-            [row.text, { impressions: row.impressions.to_i, cpm: row.cpm.to_f }]
+            [row.ad_id, { text: row.text, impressions: row.impressions.to_i, cpm: row.cpm.to_f }]
           end
         end
 
@@ -48,10 +49,6 @@ module SponsoredLogs
 
         private
 
-        def digest_for(text)
-          Digest::SHA256.hexdigest(text.to_s)
-        end
-
         # Defined lazily so requiring this file never needs ActiveRecord loaded.
         #
         def build_default_model

data/lib/sponsored_logs/ledger/store/base.rb

@@ -12,14 +12,18 @@ module SponsoredLogs
       #
       class Base
         # Record a single impression for the given normalized ad hash
-        # ({ text:, weight:, cpm: }). Called once per emitted message.
+        # ({ id:, text:, weight:, cpm: }). Called once per emitted message.
+        # Tallies are keyed by the stable ad id (SponsoredLogs::Advertisers
+        # Identity.id_for), not the mutable text, so editing copy never resets
+        # a count.
         #
         def record(_ad)
           raise NotImplementedError, "#{self.class}#record must be implemented"
         end
 
-        # Return the current tallies as { text => { impressions: Integer,
-        # cpm: Float } }. The ledger derives everything else from this.
+        # Return the current tallies as { id => { text: String, impressions:
+        # Integer, cpm: Float } }. Text is a display value here, not the key;
+        # the ledger derives everything else from this.
         #
         def snapshot
           raise NotImplementedError, "#{self.class}#snapshot must be implemented"

data/lib/sponsored_logs/ledger/store/memory.rb

@@ -3,9 +3,10 @@
 module SponsoredLogs
   module Ledger
     module Store
-      # Default adapter. Keeps impression counts and CPMs in memory, keyed by ad
-      # text. Not persisted across process restarts. A mutex guards writes so the
-      # periodic thread and request threads can record concurrently.
+      # Default adapter. Keeps impression counts and CPMs in memory, keyed by the
+      # stable ad id (text stored alongside for display). Not persisted across
+      # process restarts. A mutex guards writes so the periodic thread and
+      # request threads can record concurrently.
       #
       class Memory < Base
         def initialize
@@ -13,19 +14,23 @@ module SponsoredLogs
           @mutex = Mutex.new
           @impressions = Hash.new(0)
           @cpm = {}
+          @text = {}
         end
 
         def record(ad)
+          id = Identity.id_for(ad)
+
           @mutex.synchronize do
-            @impressions[ad[:text]] += 1
-            @cpm[ad[:text]] = ad[:cpm].to_f
+            @impressions[id] += 1
+            @cpm[id] = ad[:cpm].to_f
+            @text[id] = ad[:text].to_s
           end
         end
 
         def snapshot
           @mutex.synchronize do
-            @impressions.each_with_object({}) do |(text, count), acc|
-              acc[text] = { impressions: count, cpm: @cpm[text].to_f }
+            @impressions.each_with_object({}) do |(id, count), acc|
+              acc[id] = { text: @text[id], impressions: count, cpm: @cpm[id].to_f }
             end
           end
         end
@@ -34,6 +39,7 @@ module SponsoredLogs
           @mutex.synchronize do
             @impressions = Hash.new(0)
             @cpm = {}
+            @text = {}
           end
           self
         end

data/lib/sponsored_logs/ledger/store/redis.rb

@@ -11,24 +11,28 @@ module SponsoredLogs
           @client = client || build_default_client
           @impressions_key = "#{namespace}:impressions"
           @cpm_key = "#{namespace}:cpm"
+          @text_key = "#{namespace}:text"
         end
 
         def record(ad)
-          @client.hincrby(@impressions_key, ad[:text], 1)
-          @client.hset(@cpm_key, ad[:text], ad[:cpm].to_f)
+          id = Identity.id_for(ad)
+          @client.hincrby(@impressions_key, id, 1)
+          @client.hset(@cpm_key, id, ad[:cpm].to_f)
+          @client.hset(@text_key, id, ad[:text].to_s)
         end
 
         def snapshot
           impressions = @client.hgetall(@impressions_key)
           cpm = @client.hgetall(@cpm_key)
+          text = @client.hgetall(@text_key)
 
-          impressions.each_with_object({}) do |(text, count), acc|
-            acc[text] = { impressions: count.to_i, cpm: cpm[text].to_f }
+          impressions.each_with_object({}) do |(id, count), acc|
+            acc[id] = { text: text[id], impressions: count.to_i, cpm: cpm[id].to_f }
           end
         end
 
         def reset
-          @client.del(@impressions_key, @cpm_key)
+          @client.del(@impressions_key, @cpm_key, @text_key)
           self
         end
 

data/lib/sponsored_logs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SponsoredLogs
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/sponsored_logs.rb

@@ -5,6 +5,7 @@ require "logger"
 require_relative "sponsored_logs/version"
 require_relative "sponsored_logs/color"
 require_relative "sponsored_logs/advertisers"
+require_relative "sponsored_logs/identity"
 require_relative "sponsored_logs/flight"
 require_relative "sponsored_logs/banner"
 require_relative "sponsored_logs/ads_file"
@@ -159,39 +160,51 @@ module SponsoredLogs
 
     private
 
-    # Map of ad text => normalized config metadata (weight/cpm/flight/cap),
+    # Map of ad id => normalized config metadata (text/weight/cpm/flight/cap),
     # used to enrich report rows and drive status.
     #
     def ad_metadata
-      Advertisers.normalize(configuration.ads).to_h { |ad| [ad[:text], ad] }
+      Advertisers.normalize(configuration.ads).to_h { |ad| [ad[:id], ad] }
     end
 
     # Partition every known ad (served or configured) into running / upcoming /
-    # finished report rows by flight-and-cap status.
+    # finished report rows by flight-and-cap status. Ads are keyed by stable id;
+    # the human-readable text comes from the served ledger entry or config meta.
     #
     def grouped_report_rows
       now = Time.now
       metas = ad_metadata
       counts = ledger.impression_counts
-      served = ledger.entries.to_h { |entry| [entry.text, entry] }
+      served = ledger.entries.to_h { |entry| [entry.id, entry] }
 
       grouped = Hash.new { |h, k| h[k] = [] }
-
-      (served.keys + metas.keys).uniq.each do |text|
-        meta = metas[text] || {}
-        status = Advertisers.status(meta, now, counts[text].to_i)
-        row = report_row(text, meta, served[text], status)
-
-        case status
-        when :scheduled then grouped[:upcoming] << row
-        when :ended, :exhausted then grouped[:finished] << row
-        else grouped[:running] << row if served[text]
-        end
+      (served.keys + metas.keys).uniq.each do |id|
+        meta = metas[id] || {}
+        entry = served[id]
+        bucket, row = report_bucket_for(meta, entry, now, counts[id].to_i)
+        grouped[bucket] << row if bucket
       end
 
       grouped
     end
 
+    # Classify one ad into its report bucket (:running / :upcoming / :finished)
+    # and build its row. Text comes from the served ledger entry (latest copy)
+    # or, for an unserved configured ad, its config meta. Running rows are
+    # impression-driven, so an unserved running ad returns a nil bucket.
+    #
+    def report_bucket_for(meta, entry, now, count)
+      text = entry ? entry.text : meta[:text]
+      status = Advertisers.status(meta, now, count)
+      row = report_row(text, meta, entry, status)
+
+      case status
+      when :scheduled then [:upcoming, row]
+      when :ended, :exhausted then [:finished, row]
+      else entry ? [:running, row] : [nil, row]
+      end
+    end
+
     # A single report row. Impressions/spend come from the ledger entry when the
     # ad has served, otherwise zero; window/cap come from config metadata.
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sponsored_logs
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Kerri Miller
@@ -128,6 +128,7 @@ files:
 - lib/sponsored_logs/engine.rb
 - lib/sponsored_logs/env.rb
 - lib/sponsored_logs/flight.rb
+- lib/sponsored_logs/identity.rb
 - lib/sponsored_logs/injector.rb
 - lib/sponsored_logs/ledger/report.rb
 - lib/sponsored_logs/ledger/store/active_record.rb