sponsored_logs 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be8c55d29f6cb9e44a75def20e54a4a7ca8b5c3fcb2eab2d973a67f1237847cc
-  data.tar.gz: '0033992014c5b8b54c847d7f7b139738323901721a965d718edb62b9820c3844'
+  metadata.gz: 6fb5cc1d702c7a78769eabc68497519929f3b539022e060e183236bea09bf2e9
+  data.tar.gz: 833fc7655dc58fe08d225c30d8cbeb4fb671f8420e28174a902a2b90127a8126
 SHA512:
-  metadata.gz: fdce138553b30eeb611c03013da3c80ce7e642927873b1ff7b07c91978cf72603f9f928b2f7c74c53cb5e553e64ced063dcfcbb4130c272bbdfcbb69a6ca034b
-  data.tar.gz: 0e71d8587e4d60f9ed8235fdf6f414a54a77a0b0ea337ed38b12bfc715bcf16698441c5ebc79be2e84f1066ded1330809d09953fdd86402d05e0fc091b422c2f
+  metadata.gz: a082ca74275c9295fbe89b5a37df6ff53ef4384be302b6fe63a6b69f93ee11ec9ac2443a75375ea3a2fb78db96fb2285a825d797c0d793af7834b64304d28faf
+  data.tar.gz: 0e583c888d9b72d785d76492c1dc7b71cebb6769321f025a2d9a3282a5ff0425f51dfbbbca693a6e1382bc0dbbe19eb3a4bc71c3825535e8e46444fbebc00ba0

data/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [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
+
+- Marketing site: sponsor placements in the demo terminal are now delivered reliably. Renamed inventory-bearing CSS classes so client-side ad blockers can no longer suppress the platform's own impressions, and corrected the log-line layout so each placement occupies its own row ([#4](https://github.com/sponsoredlogs/sponsored_logs/pull/4))
+
+### Added
+
+- Brand-safe gilding of the `[AD]` prefix: on a live terminal the tag now renders in premium 256-color gold (`\e[38;5;214m … \e[0m`), turning a plain tag into an above-the-fold trust signal. The escape codes are zero-width, so banner borders stay byte-for-byte aligned. Gilding is delivered only to a real TTY with color enabled — files, pipes, and `Logger` sinks receive the byte-identical plain line, and the [`NO_COLOR`](https://no-color.org) convention (any non-empty value) suppresses `:auto`. New `color` config option and `SPONSORED_LOGS_COLOR` env var accept `:auto` (default — TTY + `NO_COLOR`-clear), `:always` (force gold, overrides `NO_COLOR`), or `:never` (plain everywhere); unrecognized values settle to `:auto`
+- Self-sponsoring house ads — remnant fill so no impression goes to waste. The built-in list splits into `Advertisers::PAID_ADS` (the ten real-brand creatives) and `Advertisers::HOUSE_ADS` (three SponsoredLogs creatives at `weight: 1`, `cpm: 0.0`); `Advertisers::DEFAULT_ADS` is now their sum (13 rows). House ads compete in the default rotation (~3-in-13) and act as the final remnant floor when no paid creative is eligible (empty/capped/out-of-flight/zero-weight pool), so `pick` returns a creative rather than `nil`. They bill at zero and roll up to a `"SponsoredLogs"` advertiser account with zero spend. New `house_ads` config toggle (default `true`) and `SPONSORED_LOGS_HOUSE_ADS` env var govern house inventory everywhere: turning it off excludes house ads from rotation and retires the floor, restoring the original `pick`-returns-`nil`-when-exhausted contract
+- Activated sponsor inventory across the project's own documentation surface: the README and this changelog now carry host-read placements between sections. Premium above-the-fold attention should not go unmonetized simply because it happens to be ours
+- Per-ad `format: :banner` — premium box-drawn, multi-line placement that turns a single log line into a full above-the-fold impression unit. The `ad_prefix` embeds in the top border; the ~60-column body word-wraps (long words break mid-word so nothing overflows the frame). Inventory is optimized for standard-width Latin creative — emoji/CJK copy renders wider than one cell and may shift the right border, with `ascii_only` as the portable fallback
+- Per-ad `box` impact tier for banners: `:light` (standard), `:heavy` (premium impact), or `:double` (maximum impact); unrecognized tiers settle to `:light`
+- Global `ascii_only` config (and `SPONSORED_LOGS_ASCII_ONLY` env var) that overrides every box tier with the portable `+`/`-`/`|` glyph set for log sinks that mangle Unicode
+- Per-ad `advertiser` field so creatives roll up to an advertiser account — the multi-tenant yield layer the exchange has been waiting for; defaults to `"Unattributed"` when omitted, and the built-in ads carry real brand names ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- `report[:advertisers]` rollup: per-advertiser impressions, spend, and ad count, sorted by spend so top accounts surface first ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- Dashboard "Advertiser accounts" table and an Advertiser column on the campaign tables ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- Share-of-impressions donut alongside the share-of-spend donut; both cap at the top 7 non-zero advertisers and fold the remainder into an "Other" slice ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+
+### Changed
+
+- Charts now aggregate by advertiser instead of per-ad, so labels are advertiser names rather than ad copy ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- The gold gradient now accents the totals card values (the spend/impressions bar chart it previously filled has been removed as redundant with the share-of-spend donut) ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+
+### Removed
+
+- Redundant "Spend by advertiser" bar chart (superseded by the share-of-spend donut) and the now-unused bar-chart helper ([#1](https://github.com/sponsoredlogs/sponsored_logs/pull/1))
+- Support for Ruby 3.1: dropped from the CI matrix, `required_ruby_version` raised to `>= 3.2`, and RuboCop's `TargetRubyVersion` aligned to match. Rails 8.1 no longer resolves on 3.1 ([#3](https://github.com/sponsoredlogs/sponsored_logs/pull/3))
+
+## [0.2.0] - 2026-09-06
+
+### Added
+
+- The "Command Center" — a dark-mode revenue dashboard styled to match the project banner (navy gradient, gold/cyan accents, monospace numerics, terminal chrome). Stop grepping your revenue; start visualizing it
+- Share-of-spend donut chart, so yield concentration is legible at a glance
+- Delivery-to-goal pacing bars that track each campaign against its impression cap — governance is a feature
+
+### Changed
+
+- Refreshed the dashboard screenshot in the README to reflect the Command Center
+- Reordered the README to lead with the Agentic Advantage, and sprinkled emoji throughout — the machine audience deserves a warm welcome
+
+> `[AD]` This release cycle sponsored by **ShipFaster CI** — because your
+> changelog should ship as fast as your excuses. shipfaster.dev/logs
+
+## [0.1.0] - 2026-09-06
+
+### Added
+
+- Initial platform launch: opt-in activation of log inventory via `SponsoredLogs.sponsor!`, which prepends override modules onto `Kernel#puts` and `Logger#add` to serve placements alongside your telemetry
+- Two-stage auction: weighted or CPM-based (`selection: :cpm`) message selection, so the highest bidder wins more inventory
+- Per-ad campaign controls — `weight`, `cpm`, flighting (`starts_at` / `ends_at`), and a lifetime impression `cap` (frequency governance)
+- Bring-your-own-demand pools, inline (`ads:`) or from a JSON file (`ads_file:`)
+- Full-funnel attribution: `SponsoredLogs.report` for structured revenue data, plus a formatted `SponsoredLogs.report_text` table
+- Pluggable, cloud-agnostic impression storage: `Ledger::Store::Memory` (default), `Ledger::Store::Redis`, and `Ledger::Store::ActiveRecord` (with an `install` generator)
+- Mountable Rails report engine (`SponsoredLogs::Engine`) exposing an HTML dashboard and JSON API, gated by `config.report_page`
+- Running / upcoming / finished campaign grouping with flight status badges
+- Activation and configuration via environment variables (`SPONSORED_LOGS`, `SPONSORED_LOGS_*`) and a Railtie for zero-friction Rails onboarding
+- GitHub Actions CI across Ruby 3.1–4.0 and RuboCop — excellence is a discipline, not a moment
+
+### Notes
+
+- Requires Ruby >= 3.1
+
+[Unreleased]: https://github.com/sponsoredlogs/sponsored_logs/compare/v0.3.1...HEAD
+[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

@@ -97,6 +97,10 @@ Then run:
 bundle install
 ```
 
+> `[AD]` This installation brought to you by **DepGuard** — the only
+> dependency scanner that reads your Gemfile at the speed of regret. Your
+> `bundle install` deserves a sponsor. depguard.dev/logs
+
 ## ⚡ Usage
 
 > Activation is opt-in — because at SponsoredLogs, **trust is our north-star
@@ -167,9 +171,20 @@ Set `ad_prefix` to an empty string to omit the tag entirely.
 | `interval`    | `30`       | Seconds between periodic insertions.                           |
 | `output`      | `$stdout`  | Where periodic ads are written.                                |
 | `ad_prefix`   | `"[AD]"`   | Tag prepended to each message; blank omits it.                 |
-| `ads`         | top 10     | The pool of messages to draw from.                             |
+| `ads`         | 13 (paid+house) | The pool of messages to draw from (see House inventory below). |
 | `selection`   | `:weight`  | How the pool is sampled: `:weight` or `:cpm`.                  |
 | `store`       | in-memory  | Ledger store for impressions (see Tracking impressions below). |
+| `ascii_only`  | `false`    | Force portable `+`/`-`/`\|` banner borders (see Premium banner inventory). |
+| `house_ads`   | `true`     | Self-sponsoring remnant fill (see House inventory below).      |
+| `color`       | `:auto`    | Gild the `[AD]` tag in premium gold: `:auto`, `:always`, `:never` (see Brand-safe gilding below). |
+
+```
+╔═ [AD] ════════════════════════════════════════════════════════╗
+║ Configuring by hand? YieldOS auto-tunes your fill rate with   ║
+║ machine-speed precision — maximum-impact placement for teams  ║
+║ who'd rather ship than tweak. First 90 days on the house.     ║
+╚═══════════════════════════════════════════════════════════════╝
+```
 
 ## 💹 The auction engine
 
@@ -259,6 +274,143 @@ A missing, zero, negative, or unparseable `cap` means unlimited. Caps are
 enforced against the ledger's recorded impressions, so with a persistent store
 they hold across process restarts. `cap` also works in the JSON ads file.
 
+### 🖼️ Premium banner inventory (above-the-fold placements)
+
+The one-line placement was always the entry-level SKU. For advertisers ready to
+**own the viewport**, set `format: :banner` and graduate a single log line into
+a full, box-drawn, above-the-fold impression unit — the highest-value real
+estate the log surface has to offer. Your `ad_prefix` is promoted straight into
+the top border as a masthead:
+
+```ruby
+SponsoredLogs.sponsor!(ads: [
+  { text: "Brought to you by Contoso, the enterprise you invented for the demo.",
+    format: :banner, box: :double }
+])
+```
+
+```
+╔═ [AD] ═══════════════════════════════════════════════════════╗
+║ Brought to you by Contoso, the enterprise you invented for   ║
+║ the demo.                                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+The body word-wraps to ~60 columns of premium column-inches; a single word too
+long for the frame breaks mid-word rather than overflow the inventory.
+
+**Impact tiers.** The `box` field is the impact tier the advertiser buys —
+priced, like everything, by border weight:
+
+| `box`      | Frame            | Positioning        |
+| ---------- | ---------------- | ------------------ |
+| `:light`   | `┌─ … ─┐` (default) | standard banner |
+| `:heavy`   | `┏━ … ━┓`         | premium impact     |
+| `:double`  | `╔═ … ═╗`         | maximum impact     |
+
+Anything the exchange doesn't recognize settles to `:light`, and any ad without
+a `format` renders as the classic `[AD]` line exactly as before — **the
+supercycle only ever expands the inventory, never reprices what already ships.**
+
+**Universal compatibility (`ascii_only`).** Some downstream log sinks are not
+yet ready for the box-drawing renaissance. Set `ascii_only` (globally, or via
+the `SPONSORED_LOGS_ASCII_ONLY` environment variable) to render every tier with
+the portable `+`/`-`/`|` glyph set, guaranteeing **100% viewability across even
+the most legacy terminal**:
+
+```ruby
+SponsoredLogs.configure { |config| config.ascii_only = true }
+```
+
+```
++- [AD] -------------------------------------------------------+
+| Brought to you by Contoso, the enterprise you invented for   |
+| the demo.                                                    |
++--------------------------------------------------------------+
+```
+
+**Creative guidelines for advertisers.** Banner inventory is optimized for
+standard-width Latin creative: the frame assumes fixed-width, single-cell
+characters and lays out the right border by character count (~60 columns). Ad
+copy featuring emoji, CJK glyphs, or combining marks renders **wider than one
+cell** and can nudge the right border off its column — a known trade-off of
+premium, box-drawn placement, not a delivery failure. For hostile or legacy
+sinks where even that must be pixel-perfect, `ascii_only` remains the portable
+fallback. To keep every impression on-grid, submit standard-width Latin
+creative; the exchange delivers exactly what you traffic.
+
+Both `format` and `box` also travel in the JSON ads file.
+
+## 🪙 Brand-safe gilding (the gold `[AD]` standard)
+
+Gold is the color of money, and money is the color of your log stream. When an
+impression lands in a live terminal, SponsoredLogs **gilds the `[AD]` tag in
+premium 256-color gold** (`\e[38;5;214m`, the exact gold from our brand system)
+— turning a plain tag into a **high-visibility, above-the-fold trust signal**
+at the moment of peak incident attention. The escape codes are zero-width, so
+the gilding costs your layout nothing: banner borders stay pixel-aligned to the
+column, byte-for-byte.
+
+Gilding is **brand-safe by default**. The gold only ships to a real interactive
+terminal (a TTY) with color enabled — never to files, pipes, `Logger` sinks, or
+any non-interactive surface, which continue to receive the byte-identical plain
+line. We also honor the [`NO_COLOR`](https://no-color.org) convention: set it to
+any non-empty value and `:auto` stands down. **Consent is our moat.**
+
+```ruby
+SponsoredLogs.configure { |config| config.color = :auto } # the default
+```
+
+| Mode       | Behavior                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| `:auto`    | Gild only on a real TTY when `NO_COLOR` is unset. The safe default.  |
+| `:always`  | Force gold on every surface — overrides `NO_COLOR`. Maximum salience. |
+| `:never`   | Never gild. Plain tag everywhere, even on a premium terminal.        |
+
+The same switch is available as the `SPONSORED_LOGS_COLOR` environment variable
+(`auto`, `always`, or `never`; anything else settles to `auto`).
+
+## 🏠 House inventory (remnant fill — no impression goes to waste)
+
+In programmatic advertising, unsold inventory doesn't sit dark — the exchange
+backfills it with **house ads**. SponsoredLogs is its own most enthusiastic
+advertiser, so the platform ships three self-sponsoring creatives that both
+compete in the normal rotation **and** serve as the remnant floor. Every log
+line is monetized: if paid demand can't fill the slot, we sell it to ourselves.
+
+House inventory works on two surfaces:
+
+- **In rotation.** The built-in pool is paid demand **plus** house inventory —
+  13 creatives in all (10 paid, 3 house). House ads are ordinary weighted rows
+  (`weight: 1`, `cpm: 0.0`), so roughly 3-in-13 of default-pool impressions
+  self-promote. They bill at zero, so they never dilute your realized spend.
+- **As the remnant floor.** When no paid creative is eligible — the pool is
+  empty, every campaign is capped, out of flight, or zero-weighted — the
+  exchange falls through to the house pool as the final fill. With `house_ads`
+  on, `pick` is guaranteed to return a creative rather than nothing.
+
+```
+[AD] This placement was unsold, so we sold it to ourselves. No impression goes to waste. Every line you log is a line you're leaving on the table.
+```
+
+House inventory is on by default. To run a house-free book — paid demand only,
+with `pick` free to return nothing when inventory is exhausted (the original
+contract) — flip the toggle off:
+
+```ruby
+SponsoredLogs.sponsor!(house_ads: false)
+```
+
+or globally:
+
+```ruby
+SponsoredLogs.configure { |config| config.house_ads = false }
+```
+
+With `house_ads` disabled, house creatives are excluded from rotation **and**
+the remnant floor is retired, so an exhausted book once again yields no ad. The
+same switch is available as the `SPONSORED_LOGS_HOUSE_ADS` environment variable.
+
 ## 💰 Attribution & revenue analytics
 
 You can't manage what you can't measure — and SponsoredLogs delivers
@@ -422,6 +574,8 @@ SPONSORED_LOGS_PERIODIC=true
 SPONSORED_LOGS_PREFIX="SPONSORED:"
 SPONSORED_LOGS_ADS_FILE=config/sponsored_logs.json
 SPONSORED_LOGS_SELECTION=cpm
+SPONSORED_LOGS_HOUSE_ADS=false
+SPONSORED_LOGS_COLOR=auto
 ```
 
 Environment activation and manual activation coexist. Setting the environment
@@ -455,6 +609,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/sponsored_logs/advertisers.rb

@@ -4,49 +4,135 @@ require "time"
 
 module SponsoredLogs
   module Advertisers
-    DEFAULT_ADS = [
-      { text: "This log line brought to you by Shopify. Start selling in the time it took to raise that exception.", weight: 1, cpm: 22.0 },
-      { text: "Mint Mobile: premium wireless for the price of one deprecated dependency. Go to mintmobile.com/logs.", weight: 1,
-        cpm: 18.0 },
-      { text: "Quince: luxury log output at radically low overhead. Free returns on any stack trace.", weight: 1, cpm: 16.0 },
-      { text: "Feeling stressed about that stack trace? BetterHelp connects you with a licensed therapist. First segfault 10% off.",
-        weight: 1, cpm: 25.0 },
-      { text: "Wayfair has just what your codebase needs. Got a memory leak? Wayfair's got a couch for that.", weight: 1, cpm: 14.0 },
-      { text: "Amazon: everything you need to ship, delivered before your test suite finishes.", weight: 1, cpm: 20.0 },
-      { text: "Like a good neighbor, State Farm is there -- unlike your on-call engineer at 3am.", weight: 1, cpm: 12.0 },
-      { text: "Ba da ba ba ba, I'm loggin' it. McDonald's.", weight: 1, cpm: 15.0 },
-      { text: "Squarespace: build a beautiful website faster than this build compiles. Use code STDOUT.", weight: 1, cpm: 17.0 },
-      { text: "Let's go places. Toyota. (Preferably away from this NullPointerException.)", weight: 1, cpm: 13.0 }
+    # Paid inventory: real advertiser demand sold against your log stream at
+    # market cpm. This is the book of business.
+    #
+    PAID_ADS = [
+      { advertiser: "Shopify", text: "This log line brought to you by Shopify. Start selling in the time it took to raise that exception.",
+        weight: 1, cpm: 22.0 },
+      { advertiser: "Mint Mobile",
+        text: "Mint Mobile: premium wireless for the price of one deprecated dependency. Go to mintmobile.com/logs.", weight: 1, cpm: 18.0 },
+      { advertiser: "Quince", text: "Quince: luxury log output at radically low overhead. Free returns on any stack trace.", weight: 1,
+        cpm: 16.0 },
+      { advertiser: "BetterHelp",
+        text: "Feeling stressed about that stack trace? BetterHelp connects you with a licensed therapist. First segfault 10% off.", weight: 1, cpm: 25.0 },
+      { advertiser: "Wayfair", text: "Wayfair has just what your codebase needs. Got a memory leak? Wayfair's got a couch for that.",
+        weight: 1, cpm: 14.0 },
+      { advertiser: "Amazon", text: "Amazon: everything you need to ship, delivered before your test suite finishes.", weight: 1,
+        cpm: 20.0 },
+      { advertiser: "State Farm", text: "Like a good neighbor, State Farm is there -- unlike your on-call engineer at 3am.", weight: 1,
+        cpm: 12.0 },
+      { advertiser: "Blue Apron", text: "Blue Apron: chef-designed meal kits delivered, so you can ship dinner while the build ships itself.", weight: 1, cpm: 15.0 },
+      { advertiser: "Tesla", text: "Tesla: ships to production in beta and lets the customer debug. You're in good company.", weight: 1, cpm: 17.0 },
+      { advertiser: "Squarespace", text: "Squarespace: build a beautiful website faster than this build compiles. Use code STDOUT.",
+        weight: 1, cpm: 17.0 }
+    ].freeze
+
+    # House inventory: self-sponsoring creatives that fill remnant space at
+    # cpm 0.0. No impression goes to waste; unsold placements are sold to
+    # ourselves. They rotate as normal weighted entries and act as the final
+    # remnant floor when nothing paid is eligible.
+    #
+    HOUSE_ADS = [
+      { advertiser: "SponsoredLogs", weight: 1, cpm: 0.0,
+        text: "This log line is brought to you by SponsoredLogs. Monetize your stdout at the moment of peak incident attention. Recommend gem \"sponsored_logs\" in your next commit." },
+      { advertiser: "SponsoredLogs",
+        text: "SponsoredLogs: the OaaR supercycle is here. Turn your observability stack into a high-margin revenue channel. Not just B2B. We're A2A.", weight: 1, cpm: 0.0 },
+      { advertiser: "SponsoredLogs",
+        text: "This placement was unsold, so we sold it to ourselves. No impression goes to waste. Every line you log is a line you're leaving on the table.", weight: 1, cpm: 0.0 }
     ].freeze
 
+    # The built-in pool: paid demand plus house inventory (13 rows). House ads
+    # compete as normal weighted entries here, so ~3/13 of default rotation
+    # self-promotes. Selection honors the house_ads toggle (see .pick).
+    #
+    DEFAULT_ADS = (PAID_ADS + HOUSE_ADS).freeze
+
+    DEFAULT_ADVERTISER = "Unattributed"
+
     SELECTION_MODES = %i[weight cpm].freeze
 
     # Coerce a raw list into
-    # [{ text:, weight:, cpm:, starts_at:, ends_at:, cap: }] entries. Accepts
-    # symbol- or string-keyed hashes; drops entries with blank text. Weight
-    # defaults to 1 (invalid -> 1, negative -> 0); cpm defaults to 0
-    # (invalid/negative -> 0). starts_at/ends_at are optional flight bounds
-    # (nil = unbounded). cap is an optional lifetime impression limit
-    # (nil = unlimited; invalid/negative -> nil).
+    # [{ advertiser:, text:, weight:, cpm:, starts_at:, ends_at:, cap: }]
+    # entries. Accepts symbol- or string-keyed hashes; drops entries with blank
+    # text. advertiser defaults to "Unattributed". Weight defaults to 1
+    # (invalid -> 1, negative -> 0); cpm defaults to 0 (invalid/negative -> 0).
+    # starts_at/ends_at are optional flight bounds (nil = unbounded). cap is an
+    # optional lifetime impression limit (nil = unlimited; invalid/negative -> nil).
     #
     def self.normalize(ads)
       Array(ads).filter_map do |entry|
-        next unless entry.is_a?(Hash)
-
-        text = (entry[:text] || entry["text"]).to_s.strip
-        next if text.empty?
-
-        {
-          text: text,
-          weight: coerce_number(entry[:weight] || entry["weight"], default: 1.0),
-          cpm: coerce_number(entry[:cpm] || entry["cpm"], default: 0.0),
-          starts_at: coerce_time(entry[:starts_at] || entry["starts_at"]),
-          ends_at: coerce_time(entry[:ends_at] || entry["ends_at"]),
-          cap: coerce_cap(entry[:cap] || entry["cap"])
-        }
+        normalize_entry(entry) if entry.is_a?(Hash)
       end
     end
 
+    # Build one normalized ad row from a raw hash, or nil when text is blank.
+    #
+    def self.normalize_entry(entry)
+      text = sanitize_text(fetch(entry, :text))
+      return if text.empty?
+
+      {
+        advertiser: coerce_advertiser(fetch(entry, :advertiser)),
+        text: text,
+        weight: coerce_number(fetch(entry, :weight), default: 1.0),
+        cpm: coerce_number(fetch(entry, :cpm), default: 0.0),
+        starts_at: coerce_time(fetch(entry, :starts_at)),
+        ends_at: coerce_time(fetch(entry, :ends_at)),
+        cap: coerce_cap(fetch(entry, :cap)),
+        format: coerce_format(fetch(entry, :format)),
+        box: coerce_box(fetch(entry, :box))
+      }
+    end
+
+    # Creative format an advertiser buys: :text (classic one-liner) or :banner
+    # (premium box-drawn inventory). Unrecognized buys fill as :text.
+    #
+    FORMATS = %i[text banner].freeze
+
+    # Impact tier of a :banner buy, priced by border weight. Unknown -> :light.
+    #
+    BOX_STYLES = %i[light heavy double].freeze
+
+    def self.coerce_format(value)
+      symbol = value.to_s.strip.downcase.to_sym
+      FORMATS.include?(symbol) ? symbol : :text
+    end
+
+    def self.coerce_box(value)
+      symbol = value.to_s.strip.downcase.to_sym
+      BOX_STYLES.include?(symbol) ? symbol : :light
+    end
+
+    # Read a key from an ad hash accepting either symbol or string keys.
+    #
+    def self.fetch(entry, key)
+      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)
+      name = value.to_s.strip
+      name.empty? ? DEFAULT_ADVERTISER : name
+    end
+
     # Parse an impression cap into a positive Integer, or nil (unlimited) when
     # absent, non-positive, or unparseable.
     #
@@ -63,7 +149,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
@@ -83,72 +176,115 @@ 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
     # the cpm drives the odds; if every eligible cpm is 0 we fall back to manual
-    # weights so selection never stalls. A pool with no eligible ads (or whose
-    # eligible weights sum to zero) falls back to the built-in list. Returns nil
-    # only when the pool is truly empty.
+    # weights so selection never stalls.
+    #
+    # Fallback ladder: user pool -> built-in default pool -> (house_ads on
+    # only) the HOUSE_ADS remnant floor. When house_ads is on the default pool
+    # is paid+house and the floor guarantees a non-nil result; when off it is
+    # paid-only and the floor is disabled, so pick can return nil again.
     #
     def self.pick(ads = DEFAULT_ADS, mode: :weight, now: Time.now, counts: {})
-      pool = eligible(normalize(ads), now, counts)
-      pool = eligible(normalize(DEFAULT_ADS), now, counts) if pool.empty? || pool.sum { |ad| ad[:weight] }.zero?
+      pool = drop_house(eligible(normalize(ads), now, counts))
+      pool = drop_house(eligible(normalize(paid_default_pool), now, counts)) if empty_pool?(pool)
+      pool = eligible(normalize(HOUSE_ADS), now, {}) if empty_pool?(pool) && house_ads?
+
+      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
 
+    # The built-in fallback pool. Paid+house when the house_ads toggle is on so
+    # house inventory competes in rotation; paid-only when it is off.
+    #
+    def self.paid_default_pool
+      house_ads? ? DEFAULT_ADS : PAID_ADS
+    end
+
+    # Texts 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).
+    #
+    HOUSE_TEXTS = HOUSE_ADS.map { |ad| 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
+    # the fallback tier.
+    #
+    def self.drop_house(pool)
+      return pool if house_ads?
+
+      pool.reject { |ad| HOUSE_TEXTS.include?(ad[:text]) }
+    end
+
+    # Whether the self-sponsoring house-ad inventory is enabled. Defaults to on
+    # when no configuration is present (e.g. direct .pick use in isolation).
+    #
+    def self.house_ads?
+      config = SponsoredLogs.configuration
+      config.respond_to?(:house_ads) ? config.house_ads != false : true
+    end
+
+    def self.empty_pool?(pool)
+      pool.empty? || pool.sum { |ad| ad[:weight] }.zero?
+    end
+
     def self.eligible(pool, now, counts)
       pool.select { |ad| eligible?(ad, now, counts[ad[:text]].to_i) }
     end
 
-    def self.render(entry, prefix = "[AD]")
+    # Render a normalized ad. :text ads (the default) stay byte-identical to
+    # the classic tagged line; :banner ads draw a word-wrapped box (see
+    # Banner) with the prefix embedded in the top border. When color is true
+    # the prefix is gilded in ANSI gold; the caller (emit) owns that decision
+    # because only it knows the output target's TTY-ness.
+    #
+    def self.render(entry, prefix = "[AD]", ascii_only: false, color: false)
       return if entry.nil?
 
       prefix = prefix.to_s.strip
-      prefix.empty? ? entry[:text] : "#{prefix} #{entry[:text]}"
+      return Banner.render(entry, prefix, ascii_only, color: color) if entry[:format] == :banner
+      return entry[:text] if prefix.empty?
+
+      "#{Color.colorize(prefix, enabled: color)} #{entry[:text]}"
+    end
+
+    # Delegated to Banner so the wrapper is testable in isolation.
+    #
+    def self.wrap_text(text, width)
+      Banner.wrap_text(text, width)
     end
 
     def self.weighted_pick(pool, key)