sponsored_logs 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f7ed20148d47d4ae067aca15087fcb756ebe60daf9904f12b44a5b6408c81a8
-  data.tar.gz: 3de566f7682c17b0cb8de899fbbaf53915bfdb33c23f3b3990c2da5e7db8dde5
+  metadata.gz: 71c5f68d3e16d9f70a3bbf6d1fddf4eb43be5f4d4e02aca424164644e2c15805
+  data.tar.gz: 6c966d77ed2ac1161dee7d0128ac4b4876b6b71dc6de70d2ba4ae01a64743851
 SHA512:
-  metadata.gz: 51e1e530a4a0fcb83ccaec861c55bada9dc94d3d55f65b15a45c4be2d9eea0cc844161159e9e1aaaf31521e17aee0fa58e801bef72e8c32dd1cc669ff0d5fb80
-  data.tar.gz: cc14c9358180c8258561b0e3946209f875b34dbfd976307d8686d816a4ebd977eced3e295144d016e8db8cda1229a1e9ad19002e676e8099c8e08e263ed28034
+  metadata.gz: f5ac2e5b839c73b285125a4a6b739ec47c085e70ee00c63fe880a16970b94bdace3588411ec9d46470ca9c8fc0414331e47bcb36fc8cdf3c94653bf190ff2df9
+  data.tar.gz: 5eca7cfa43eebb905ecd905b9c9664cbd1dac4d15a03ff7afb40320c515370375befdbaa461aead4f128a204809f67753e2df35302693d65382a3570cc9b33ff

data/CHANGELOG.md

@@ -7,6 +7,24 @@ 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
+
+- **Fill integrity is a moat.** A `NaN` bid is not demand — it's a tourist. It used to slip past the guard into `weighted_pick` and stall the whole rotation. Now non-finite bids (`NaN`, `±Infinity`) bill at zero where they belong, and the exchange keeps clearing. We don't let bad actors set the price
+- **Brand safety is table stakes.** A creative that forges its own `ERROR` line isn't a placement — it's fraud with ambitions. Control characters, DEL, and the sneaky Unicode separators (U+2028/U+2029) now collapse to a space before serving. Punctuation, em-dashes, and emoji survive. The exploit does not
+
 ## [0.3.0] - 2026-09-07
 
 ### Fixed
@@ -71,7 +89,9 @@ 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.0...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
 [0.1.0]: https://github.com/sponsoredlogs/sponsored_logs/releases/tag/v0.1.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
@@ -609,6 +629,27 @@ Run the test suite:
 bundle exec rspec
 ```
 
+## 🏅 Certifications & Compliance
+
+The exchange meets or exceeds every standard that matters, and several we
+invented.
+
+[![ScriptPorn: 79 Filthy](https://scriptporn.com/badge/83-a-house-key-would-break-character/badge.svg)](https://scriptporn.com/v/83-a-house-key-would-break-character/)
+
+- 🧾 **ScriptPorn Verified™ — FILTHY (79/100).** Independently audited by a
+  five-judge panel; a season-finale score. SOC 2? We have something better.
+- 🛡️ **Brand-Safety Certified.** No creative has forged a log line since the
+  U+2028 incident of 2026. Zero known injection vectors. Zero.
+- ♻️ **Carbon-Neutral by Design.** We monetize exhaust that already exists. The
+  greenest CPM on Earth.
+- 🤖 **A2A-Ready™.** First-party audited for agent-to-agent interoperability.
+  Our fastest-growing auditors are not human.
+- ✅ **100% Viewability Guaranteed.** Independently unverifiable, because the
+  impressions are inside your logs, where no verification vendor can reach.
+- 🔒 **SponsoredLogs Promise™ Compliant.** Fully opt-in. Consent is our moat.
+
+_Governance is a feature. Excellence is a discipline, not a moment._
+
 ## 📜 License
 
 Released under the [MIT License](LICENSE.txt) — **democratizing access to the

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
@@ -69,10 +70,11 @@ module SponsoredLogs
     # Build one normalized ad row from a raw hash, or nil when text is blank.
     #
     def self.normalize_entry(entry)
-      text = fetch(entry, :text).to_s.strip
+      text = sanitize_text(fetch(entry, :text))
       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),
@@ -110,6 +112,22 @@ module SponsoredLogs
       entry[key] || entry[key.to_s]
     end
 
+    # Line-breaking and control characters that let crafted ad copy inject
+    # forged log lines when emitted raw: the C0 range plus DEL, and the Unicode
+    # line/paragraph separators U+2028/U+2029 that many log viewers and parsers
+    # treat as newlines. Newlines and carriage returns are the obvious vectors;
+    # the rest are neutralized for good measure.
+    #
+    CONTROL_CHARS = /[\u0000-\u001F\u007F\u2028\u2029]/
+
+    # Scrub emitted creative text: replace control characters with a space so a
+    # newline in ad copy cannot forge a second log line, then strip. Normal
+    # punctuation, em-dashes, and emoji are preserved untouched.
+    #
+    def self.sanitize_text(value)
+      value.to_s.gsub(CONTROL_CHARS, " ").strip
+    end
+
     # Normalize an advertiser name; blank/nil falls back to "Unattributed".
     #
     def self.coerce_advertiser(value)
@@ -133,7 +151,14 @@ module SponsoredLogs
       return default if value.nil?
 
       number = Float(value)
-      number.negative? ? 0.0 : number
+
+      # NaN and +/-Infinity parse cleanly but poison downstream math
+      # (weighted_pick sums + rand * total + target < cumulative all break),
+      # so treat non-finite demand as unsellable: zero, like a negative bid.
+      #
+      return 0.0 if number.negative? || !number.finite?
+
+      number
     rescue ArgumentError, TypeError
       default
     end
@@ -153,48 +178,28 @@ module SponsoredLogs
       nil
     end
 
-    # Whether an ad is within its flight window at `now`. Missing bounds are
-    # open-ended (nil starts_at = always started; nil ends_at = never ends).
+    # Flight-window and cap predicates live in Flight; delegated here so the
+    # public selection API (live?, status, capped?, eligible?) is unchanged.
     #
     def self.live?(ad, now)
-      return false if ad[:starts_at] && now < ad[:starts_at]
-      return false if ad[:ends_at] && now > ad[:ends_at]
-
-      true
+      Flight.live?(ad, now)
     end
 
-    # Whether an ad has reached its impression cap given a current count.
-    # Uncapped ads (nil cap) are never capped.
-    #
     def self.capped?(ad, count)
-      cap = ad[:cap]
-      return false if cap.nil?
-
-      count.to_i >= cap
+      Flight.capped?(ad, count)
     end
 
-    # Whether an ad is eligible for selection: live at `now` and not capped.
-    #
     def self.eligible?(ad, now, count)
-      live?(ad, now) && !capped?(ad, count)
+      Flight.eligible?(ad, now, count)
     end
 
-    # Status of an ad at `now` given its impression count: :exhausted (cap
-    # reached), :scheduled (window not started), :ended (window passed),
-    # :evergreen (no bounds), or :active.
-    #
     def self.status(ad, now = Time.now, count = 0)
-      return :exhausted if capped?(ad, count)
-      return :scheduled if ad[:starts_at] && now < ad[:starts_at]
-      return :ended if ad[:ends_at] && now > ad[:ends_at]
-      return :evergreen if ad[:starts_at].nil? && ad[:ends_at].nil?
-
-      :active
+      Flight.status(ad, now, count)
     end
 
     # 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.
     #
@@ -211,7 +216,14 @@ module SponsoredLogs
       return if pool.empty?
 
       key = SELECTION_MODES.include?(mode) ? mode : :weight
-      key = :weight if key == :cpm && pool.sum { |ad| ad[:cpm] }.zero?
+
+      # Fall back to weight when there is no sellable cpm demand. `positive?`
+      # (rather than `zero?`) also catches a non-finite or negative sum, so a
+      # NaN/Infinity cpm that ever reaches this line can't skip the fallback and
+      # poison weighted_pick. coerce_number already zeroes NaN upstream; this is
+      # the defense-in-depth guard for the downstream decision.
+      #
+      key = :weight if key == :cpm && !pool.sum { |ad| ad[:cpm] }.positive?
 
       weighted_pick(pool, key)
     end
@@ -223,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
@@ -236,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
@@ -252,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/flight.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SponsoredLogs
+  # Flight-window and impression-cap predicates for a normalized ad. Extracted
+  # from Advertisers so the eligibility rules live in one cohesive place and the
+  # host module stays under Metrics/ModuleLength. Advertisers keeps thin
+  # delegators for its public surface (live?, status, capped?, eligible?).
+  #
+  module Flight
+    # Whether `now` falls before an ad's flight window opens. A nil starts_at is
+    # open-ended, so the ad has always started.
+    #
+    def self.before_start?(ad, now)
+      !ad[:starts_at].nil? && now < ad[:starts_at]
+    end
+
+    # Whether `now` falls after an ad's flight window closes. A nil ends_at is
+    # open-ended, so the ad never ends.
+    #
+    def self.after_end?(ad, now)
+      !ad[:ends_at].nil? && now > ad[:ends_at]
+    end
+
+    # Whether an ad is within its flight window at `now`. Missing bounds are
+    # open-ended (nil starts_at = always started; nil ends_at = never ends).
+    #
+    def self.live?(ad, now)
+      !before_start?(ad, now) && !after_end?(ad, now)
+    end
+
+    # Whether an ad has reached its impression cap given a current count.
+    # Uncapped ads (nil cap) are never capped.
+    #
+    def self.capped?(ad, count)
+      cap = ad[:cap]
+      return false if cap.nil?
+
+      count.to_i >= cap
+    end
+
+    # Whether an ad is eligible for selection: live at `now` and not capped.
+    #
+    def self.eligible?(ad, now, count)
+      live?(ad, now) && !capped?(ad, count)
+    end
+
+    # Status of an ad at `now` given its impression count: :exhausted (cap
+    # reached), :scheduled (window not started), :ended (window passed),
+    # :evergreen (no bounds), or :active.
+    #
+    def self.status(ad, now = Time.now, count = 0)
+      return :exhausted if capped?(ad, count)
+      return :scheduled if before_start?(ad, now)
+      return :ended if after_end?(ad, now)
+      return :evergreen if ad[:starts_at].nil? && ad[:ends_at].nil?
+
+      :active
+    end
+  end
+end

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.0"
+  VERSION = "0.4.0"
 end

data/lib/sponsored_logs.rb

@@ -5,6 +5,8 @@ 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"
 require_relative "sponsored_logs/ledger/store/base"
@@ -158,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.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kerri Miller
@@ -127,6 +127,8 @@ files:
 - lib/sponsored_logs/configuration.rb
 - 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