sentiero 1.0.0.alpha1 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d366ebafb881e12dd1d59ac702c282f6a82b7a841842c48243f1ac0a4d18e0be
-  data.tar.gz: 52229be75a9458f841898ab00dd53d8e5c3016c6b4d80efd35946ad649b2e24b
+  metadata.gz: c8bc35b365449e9111ed5dcc093ea7fceaf60d739b47e1bf13df8f7cbc83cf55
+  data.tar.gz: 39c9a76c8acf2f22d44fcc3fa88d450ef1e36a368434ba5ae143c82bd2800b30
 SHA512:
-  metadata.gz: 33cdbcd859bf98e7baf6c38f63bbf52706b6c0d6c42f9af4ff9b2fa50a60f91e1705a535ac06d7b7a0d607f640cefab532008ba634609076127292bc27b0cebc
-  data.tar.gz: 337f37bf15a0c89e343f9908b1c5cd69c986abd2e184521fc7be827f0c71dc4f6df1c0bd7885caa687191f095bb6636a1a1b175d774403676378ab594b6d7d49
+  metadata.gz: 527083a0dc823bb03343f97b41f3f40e3c629ce201dbf234613c9d615068e8e481d612f0aa0ff8a5736e6cc487f1f6d049f0d704647b0fa37e7361d4cafa4003
+  data.tar.gz: c77ebaff3d74da9cdef241db684ccb6f0b5a141a10932fd49d3af131bd4434ddb8194ee78abab087a16893c2b01a4566f0f75f98f44e17679e5107bfb2a9b0dc

data/README.md

@@ -19,13 +19,15 @@ Captures user interactions via [rrweb](https://www.rrweb.io/), stores them serve
 
 Similar to [SpectatorSport](https://github.com/bensheldon/spectator_sport) by Ben Sheldon but not bound to Rails.
 
-📖 **Full documentation: [sentiero.app](https://sentiero.app)**
+**Full documentation: [sentiero.app](https://www.sentiero.app)**
+
+**Demo: [demo.sentiero.app](https://demo.sentiero.app)** (login to dashboard with `demo`/`demo`)
 
 ### Why Sentiero?
 
 - **De-SaaS your session recording** — keep user interaction data in your own infrastructure instead of sending it to third-party services
 - **Privacy-respecting defaults** — all inputs masked by default, password masking enforced and cannot be disabled, per-element control via HTML attributes
-- **User-side controls** — respects Do Not Track (DNT) and Global Privacy Control (GPC), with support for explicit user opt-in/opt-out
+- **User-side controls** — honors Global Privacy Control (GPC) out of the box, with support for explicit user opt-in/opt-out
 - **Framework-agnostic** — drop into any Rack-compatible app, or use the dedicated Rails integration
 - **Complete but focused** — session recording, replay, and the tools around them, without trying to be an analytics platform
 
@@ -43,7 +45,7 @@ Also:
 - Session metadata,  captures URL, browser, viewport, referrer (opt-in)
 - Navigation tracking,  automatic outbound link logging (opt-in)
 - Error capture,  JS errors recorded in the timeline (opt-in)
-- Custom events,  imperative JS API or declarative `data-sentiero-track-*` HTML attributes ([docs](https://sentiero.app/guide/custom-events/))
+- Custom events,  imperative JS API or declarative `data-sentiero-track-*` HTML attributes ([docs](https://www.sentiero.app/guide/custom-events/))
 - JSON export and shareable deep-links with timestamp
 - Replay enhancers,  click overlay, scroll-depth indicator, frustration annotations (rage/dead clicks), form-interaction detail in the activity sidebar, Web Vitals badges, and a has-errors session filter
 - Cross-session [Analytics](#analytics),  pages, segments, errors, heatmaps, scroll, and forms across all recorded sessions
@@ -139,7 +141,7 @@ Include in your HTML layout (before `</body>`):
 
 That's it. Sessions are now being recorded and viewable at `/sentiero/`.
 
-> **Using Rails?** The `sentiero-rails` gem adds ActiveRecord storage, a migration generator, and view helpers. See [the Rails guide](https://sentiero.app/guide/rails/) for the full guide.
+> **Using Rails?** The `sentiero-rails` gem adds ActiveRecord storage, a migration generator, and view helpers. See [the Rails guide](https://www.sentiero.app/guide/rails/) for the full guide.
 
 > **Going to production?** Read the [Production Checklist](#production-checklist) first.
 
@@ -178,7 +180,7 @@ Use route-level auth when you need `401`/`302` responses (e.g., HTTP Basic promp
 
 The events endpoint (`EventsApp`) is intentionally public,  it receives browser-generated rrweb data. Protect it with CORS (`cors_origins`), rate limiting, and payload size limits instead.
 
-See [the authentication guide](https://sentiero.app/guide/authentication/) for the full guide including Rails, Sinatra, and plain Rack examples.
+See [the authentication guide](https://www.sentiero.app/guide/authentication/) for the full guide including Rails, Sinatra, and plain Rack examples.
 
 ## Privacy
 
@@ -247,10 +249,10 @@ Sentiero ships a compliance toolkit for GDPR/CCPA-style obligations:
 - **Server-side redaction** — the `config.redaction` engine scrubs events on ingest before they reach the store: builtin patterns (emails, tokens, cards), URL query handling (`url_mode`, allow/denylists), `custom_patterns` for server-rendered PII you can pattern-match, and a `server_proc` hook (the ingest-side backstop to `data-rr-mask`/`data-rr-block`). Redaction is fail-closed: an error in `server_proc` drops the batch rather than persisting unsanitized data.
 - **IP anonymization** — `config.anonymize_ip` (default `true`) truncates client IPs before storage; set to `false` to keep raw IPs.
 - **Data retention / purge** — set `config.retention_period` (seconds) and call `Sentiero.purge_expired!` from a scheduler, or run `rake sentiero:purge` in Rails apps.
-- **Right to erasure** — `Sentiero.erase_sessions(*ids)` / `Sentiero.erase_where(**filters)`, or `rake sentiero:erase` in Rails apps.
+- **Right to erasure** — `Sentiero.erase_sessions(ids)` / `Sentiero.erase_where(**filters)`, or `rake sentiero:erase` in Rails apps.
 - **Audit hook** — `config.audit_log` receives compliance-relevant events (opt-outs, erasures, purges) for your own logging.
 
-See [the privacy guide](https://sentiero.app/guide/privacy/) for the full privacy guide including cross-tab sessions, global recording options, and compliance details.
+See [the privacy guide](https://www.sentiero.app/guide/privacy/) for the full privacy guide including cross-tab sessions, global recording options, and compliance details, and [Implementing Consent & Opt-Out](https://www.sentiero.app/guide/consent/) for step-by-step consent-banner, opt-out-toggle, and right-to-erasure recipes.
 
 ## Analytics
 
@@ -270,7 +272,7 @@ Analytics are **compute-on-read**: there are no rollup tables, the analyzers que
 
 DashboardApp serves these routes automatically. To mount the analytics UI on its own, use the Roda helper `r.sentiero_analytics`.
 
-See [the analytics guide](https://sentiero.app/guide/analytics/) for details.
+See [the analytics guide](https://www.sentiero.app/guide/analytics/) for details.
 
 ## Shareable Replays
 
@@ -283,7 +285,7 @@ Both are gated by `config.shareable_replays` (default `false`); while disabled,
 
 > **Security:** a share file is a full session dump that leaves your infrastructure. Treat it like any other export of recorded data and only enable sharing if that's acceptable for your privacy posture.
 
-See [the sharing guide](https://sentiero.app/guide/sharing/) for details.
+See [the sharing guide](https://www.sentiero.app/guide/sharing/) for details.
 
 ## Server-side Error Tracking
 
@@ -400,7 +402,7 @@ captures and re-raises unhandled exceptions, and reads the session/window
 cookies into context). Opt out with `Sentiero::Rails.configure { |c| c.reporter_middleware = false }`.
 For non-Rails apps, add the middleware yourself: `use Sentiero::Reporter::Middleware`.
 
-See [the error tracking guide](https://sentiero.app/guide/error-tracking/) for the full guide
+See [the error tracking guide](https://www.sentiero.app/guide/error-tracking/) for the full guide
 (architecture, the `/issues` and `/custom-events` dashboards, deployment, and
 the Crystal shard).
 
@@ -476,7 +478,7 @@ end
 | `capture_metadata` | `Boolean` | `false` | Capture page URL, browser, viewport, and referrer per session |
 | `capture_errors` | `Boolean` | `false` | Capture JS errors and unhandled promise rejections as timeline events |
 | `track_navigation` | `Boolean` | `false` | Automatically log outbound link clicks as custom events |
-| `track_custom_events` | `Boolean` | `false` | Enable declarative `data-sentiero-track-*` HTML attributes for custom events ([docs](https://sentiero.app/guide/custom-events/)) |
+| `track_custom_events` | `Boolean` | `false` | Enable declarative `data-sentiero-track-*` HTML attributes for custom events ([docs](https://www.sentiero.app/guide/custom-events/)) |
 | `track_forms` | `Boolean` | `false` | Capture real form submits as `__form_submit` events for form analytics (form `name`/`id` attributes + page URL — never values) |
 | `mask_all_inputs` | `Boolean` | `true` | Mask all form input values in recordings |
 | `mask_input_options` | `Hash` | `{}` | Per-input-type masking; `password: true` is always enforced |
@@ -600,7 +602,7 @@ Requires the `redis` gem.
 
 Implement the methods defined in `Sentiero::Store` and verify with the shared contract tests.
 
-See [the storage guide](https://sentiero.app/guide/storage/) for details on all backends, Redis data structures, and building custom stores.
+See [the storage guide](https://www.sentiero.app/guide/storage/) for details on all backends, Redis data structures, and building custom stores.
 
 ## Security
 
@@ -646,7 +648,7 @@ cd frontend && npm install && npm run build
 # Output: lib/sentiero/web/assets/vendor/recorder.js
 ```
 
-See [the recorder guide](https://sentiero.app/guide/recorder/) for details on the frontend recorder's batching, compression, and retry behavior.
+See [the recorder guide](https://www.sentiero.app/guide/recorder/) for details on the frontend recorder's batching, compression, and retry behavior.
 
 ### Testing
 

data/lib/sentiero/analytics/analyzer.rb

@@ -27,10 +27,14 @@ module Sentiero
       # [sessions_scanned, hit_cap]. Counts DISTINCT sessions (not windows), so
       # `hit_cap` is correct even when a session spans several windows. Callers
       # build was_truncated as `collector.capped || hit_cap`.
-      def scan_sessions(limit: nil, since: nil, until_time: nil)
+      # types: lets the store skip fetching/parsing event types the analyzer
+      # never reads (above all type-2 DOM snapshots, which dominate stored
+      # bytes). Always include META — page segmentation and entry attribution
+      # anchor on it.
+      def scan_sessions(limit: nil, since: nil, until_time: nil, types: nil)
         scan_cap = limit || store.limits.analytics_max_scan_sessions
         seen = {}
-        store.each_session_events(limit: scan_cap, since: since, until_time: until_time) do |summary, window_id, events|
+        store.each_session_events(limit: scan_cap, since: since, until_time: until_time, types: types) do |summary, window_id, events|
           seen[summary[:session_id]] = true
           yield summary, window_id, events
         end
@@ -54,10 +58,10 @@ module Sentiero
       # anchor_ts]; consecutive same-href Metas (same-URL reloads) stay in one
       # segment. anchor_ts is the WINDOW's first timestamp for every segment:
       # replay deep-links (?t=offset) are window-relative, never segment-local.
-      def each_page_segment(events)
+      def each_page_segment(events, anchor: nil)
         return if events.empty?
 
-        anchor_ts = events.first&.fetch("timestamp", nil)
+        anchor_ts = anchor || events.first&.fetch("timestamp", nil)
 
         boundaries = [] # [start_index, url] per href change
         events.each_with_index do |event, index|
@@ -79,6 +83,14 @@ module Sentiero
         end
       end
 
+      # Replay ?t= offsets anchor on the window's TRUE first timestamp, which
+      # a typed scan may have filtered out of `events` — prefer the summary's
+      # :window_starts over events.first.
+      def window_anchor(summary, window_id, events)
+        anchor = summary[:window_starts]&.fetch(window_id, nil)
+        anchor.nil? ? events.first&.fetch("timestamp", nil) : anchor
+      end
+
       def meta_href(event)
         return nil unless event.is_a?(Hash) && event["type"] == META
 

data/lib/sentiero/analytics/browser_event_discovery.rb

@@ -21,8 +21,8 @@ module Sentiero
         rows = []
         truncated = false
 
-        _scanned, hit_cap = scan_sessions(since: since, until_time: until_time) do |summary, window_id, events|
-          anchor = events.first&.fetch("timestamp", nil)
+        _scanned, hit_cap = scan_sessions(since: since, until_time: until_time, types: [META, CUSTOM]) do |summary, window_id, events|
+          anchor = window_anchor(summary, window_id, events)
           events.each do |event|
             next unless browser_event?(event)
 

data/lib/sentiero/analytics/conversion_analyzer.rb

@@ -32,7 +32,7 @@ module Sentiero
         sessions = {}
         @truncated = false
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [META, CUSTOM]) do |summary, window_id, events|
           session_id = summary[:session_id]
           state = sessions[session_id] ||= new_state(summary, window_id)
 

data/lib/sentiero/analytics/engagement_analyzer.rb

@@ -49,7 +49,7 @@ module Sentiero
       def analyze(limit: nil, since: nil, until_time: nil)
         accumulators = {}
 
-        scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+        scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [INCREMENTAL, META, CUSTOM]) do |summary, window_id, events|
           session_id = summary[:session_id]
           acc = (accumulators[session_id] ||= new_accumulator(summary, window_id))
           accumulate_window(acc, events)

data/lib/sentiero/analytics/error_discovery.rb

@@ -19,7 +19,7 @@ module Sentiero
       def grouped_errors(sort_by: "count", since: nil, until_time: nil)
         groups = {}
 
-        _scanned, hit_cap = scan_sessions(since: since, until_time: until_time) do |summary, window_id, events|
+        _scanned, hit_cap = scan_sessions(since: since, until_time: until_time, types: [META, CUSTOM]) do |summary, window_id, events|
           collect_window(groups, summary, window_id, events)
         end
 
@@ -32,7 +32,7 @@ module Sentiero
       private
 
       def collect_window(groups, summary, window_id, events)
-        anchor = events.first&.fetch("timestamp", nil)
+        anchor = window_anchor(summary, window_id, events)
 
         events.each do |event|
           next unless ErrorCollector.error_event?(event)

data/lib/sentiero/analytics/exporter.rb

@@ -95,7 +95,7 @@ module Sentiero
         headers = %w[session_id window_id timestamp tag]
         rows = []
 
-        store.each_session_events(limit: scan_cap, since: since, until_time: until_time) do |summary, window_id, events|
+        store.each_session_events(limit: scan_cap, since: since, until_time: until_time, types: [CUSTOM]) do |summary, window_id, events|
           events.each do |event|
             next unless event["type"] == CUSTOM
             tag = event.dig("data", "tag")

data/lib/sentiero/analytics/frustration_analyzer.rb

@@ -47,7 +47,7 @@ module Sentiero
         pages = {}
         accumulation_capped = false
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [INCREMENTAL, META, CUSTOM]) do |summary, window_id, events|
           incidents = Frustration::Detectors.detect_frustration_events(events)
           next if incidents.empty?
 

data/lib/sentiero/analytics/funnel_analyzer.rb

@@ -44,10 +44,10 @@ module Sentiero
         sessions = {}
         accumulation_capped = false
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [META, CUSTOM]) do |summary, window_id, events|
           session_id = summary[:session_id]
 
-          anchor = events.first&.fetch("timestamp", nil)
+          anchor = window_anchor(summary, window_id, events)
           events.each do |event|
             tag = custom_tag(event)
             next unless tag

data/lib/sentiero/analytics/heatmap_analyzer.rb

@@ -20,7 +20,7 @@ module Sentiero
         clicks = ClickCollector.new
         representative = nil
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [INCREMENTAL, META, CUSTOM]) do |summary, window_id, events|
           session_id = summary[:session_id]
 
           each_page_segment(events) do |url, segment, _anchor|
@@ -43,7 +43,7 @@ module Sentiero
       def build_heatmap_table(since: nil, until_time: nil)
         selectors_by_url = {}
 
-        scan_sessions(since: since, until_time: until_time) do |_summary, _window_id, events|
+        scan_sessions(since: since, until_time: until_time, types: [INCREMENTAL, META, CUSTOM]) do |_summary, _window_id, events|
           each_page_segment(events) do |url, segment, _anchor|
             next unless url
 
@@ -64,7 +64,7 @@ module Sentiero
       def recorded_urls
         urls = {}
 
-        scan_sessions do |_summary, _window_id, events|
+        scan_sessions(types: [INCREMENTAL, META, CUSTOM]) do |_summary, _window_id, events|
           each_page_segment(events) do |url, _segment, _anchor|
             urls[url] = true if url && (urls.key?(url) || urls.size < MAX_URLS)
           end

data/lib/sentiero/analytics/page_report_analyzer.rb

@@ -35,7 +35,7 @@ module Sentiero
       def analyze(target_url, limit: nil, since: nil, until_time: nil)
         acc = new_accumulator
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [INCREMENTAL, META, CUSTOM]) do |summary, window_id, events|
           session_id = summary[:session_id]
 
           # Detect over the FULL window: frustration semantics span page
@@ -48,7 +48,7 @@ module Sentiero
           first_was_target = false
           target_segments = 0
 
-          each_page_segment(events) do |url, segment, anchor|
+          each_page_segment(events, anchor: window_anchor(summary, window_id, events)) do |url, segment, anchor|
             matches = url == target_url
             first_was_target = true if segment_index.zero? && matches
             last_index = segment_index if matches

data/lib/sentiero/analytics/scroll_depth_analyzer.rb

@@ -13,7 +13,7 @@ module Sentiero
       def analyze(limit: nil, since: nil, until_time: nil)
         scroll = ScrollCollector.new(max_urls: MAX_URLS)
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |_summary, _window_id, events|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [INCREMENTAL, META]) do |_summary, _window_id, events|
           each_page_segment(events) do |url, segment, _anchor|
             scroll.observe(url, segment) if url
           end

data/lib/sentiero/analytics/segmenter.rb

@@ -5,7 +5,7 @@ require_relative "../user_agent"
 
 module Sentiero
   module Analytics
-    # Filters sessions on read by browser/device/URL/metadata/has-errors/duration
+    # Filters sessions on read by browser/device/country/URL/metadata/has-errors/duration
     # (AND-combined), scanning up to the store's limits.analytics_max_scan_sessions.
     class Segmenter < Analyzer
       def initialize(
@@ -19,6 +19,7 @@ module Sentiero
         has_errors: false,
         min_duration_ms: nil,
         max_duration_ms: nil,
+        country: nil,
         since: nil,
         until_time: nil
       )
@@ -32,6 +33,8 @@ module Sentiero
         @has_errors = has_errors
         @min_duration_ms = min_duration_ms
         @max_duration_ms = max_duration_ms
+        # Normalized: Cloudflare sends uppercase ISO-2, but a custom proc may not.
+        @country = presence(country)&.upcase
         @since = since
         @until_time = until_time
       end
@@ -40,6 +43,9 @@ module Sentiero
         scan_cap = store.limits.analytics_max_scan_sessions
 
         scanned = store.list_sessions(limit: scan_cap, offset: 0, since: @since, until_time: @until_time)
+        # Collected pre-filter, in the same scan (no extra store pass): the
+        # dropdown must list every scanned country, not just the current selection.
+        countries = scanned.filter_map { |s| s[:metadata]&.[]("geo_country") }.uniq.sort
         matches = scanned.select { |summary| match?(summary) }
 
         page = matches.slice(offset, limit + 1) || []
@@ -48,7 +54,8 @@ module Sentiero
         {
           sessions: page.first(limit),
           has_next: has_next,
-          was_truncated: scanned.size >= scan_cap
+          was_truncated: scanned.size >= scan_cap,
+          countries: countries
         }
       end
 
@@ -65,6 +72,7 @@ module Sentiero
 
         browser_match?(metadata) &&
           device_match?(metadata) &&
+          country_match?(metadata) &&
           url_match?(metadata) &&
           metadata_match?(metadata) &&
           has_errors_match?(metadata) &&
@@ -83,6 +91,12 @@ module Sentiero
         UserAgent.device(metadata["userAgent"]) == @device
       end
 
+      def country_match?(metadata)
+        return true unless @country
+
+        metadata["geo_country"].to_s.upcase == @country
+      end
+
       def url_match?(metadata)
         return true unless @url_pattern
 

data/lib/sentiero/analytics/stats_aggregator/result_builder.rb

@@ -31,6 +31,8 @@ module Sentiero
             event_type_breakdown: event_type_breakdown(acc.event_types),
             browser_distribution: sort_by_count(acc.browsers),
             device_distribution: sort_by_count(acc.devices),
+            country_distribution: sort_by_count(acc.countries),
+            city_distribution: sort_by_count(acc.cities),
             top_entry_pages: top_entry_pages(acc),
             top_referrers: top_list(acc.referrers, :referrer, StatsAggregator::TOP_LIST_LIMIT),
             session_duration_buckets: acc.duration_buckets,

data/lib/sentiero/analytics/stats_aggregator.rb

@@ -18,7 +18,14 @@ module Sentiero
 
       NAVIGATION_TAG = "navigation"
 
-      INTERNAL_METADATA_KEYS = %w[userAgent url referrer viewport has_errors entry_url entry_referrer].freeze
+      # With native aggregates (SQLite) the scan reads only Meta + Custom; the
+      # type histogram, total count and per-day series come from the store in
+      # #finalize. Other stores keep the single all-types scan — the aggregate
+      # fallbacks would each re-scan the store.
+      SCAN_TYPES = [META, CUSTOM].freeze
+
+      INTERNAL_METADATA_KEYS = %w[userAgent url referrer viewport has_errors entry_url entry_referrer
+        geo_country geo_city geo_region geo_timezone].freeze
 
       MAX_NAV_KEYS = 200
       MAX_METADATA_KEYS = 50
@@ -26,6 +33,7 @@ module Sentiero
       MAX_TAG_SERIES_KEYS = 200
       MAX_OVERLAY_PROBLEMS = 200
       MAX_OCCURRENCES_PER_PROBLEM = 500
+      MAX_GEO_VALUES = 200
 
       DURATION_BUCKETS = [
         ["0-30s", 30_000],
@@ -44,7 +52,7 @@ module Sentiero
         acc = new_accumulator(since, until_time)
         seen_sessions = {}
 
-        store.each_session_events(limit: scan_cap, since: since, until_time: until_time) do |summary, _window_id, events|
+        store.each_session_events(limit: scan_cap, since: since, until_time: until_time, types: scan_types) do |summary, _window_id, events|
           accumulate_window(acc, seen_sessions, summary, events)
         end
 
@@ -73,7 +81,7 @@ module Sentiero
         current = {acc: new_accumulator(since, until_time), seen: {}}
         prior = {acc: new_accumulator(prior_since, prior_until), seen: {}}
 
-        store.each_session_events(limit: scan_cap, since: prior_since, until_time: until_time) do |summary, _window_id, events|
+        store.each_session_events(limit: scan_cap, since: prior_since, until_time: until_time, types: scan_types) do |summary, _window_id, events|
           bucket = (summary[:updated_at] >= since) ? current : prior
           accumulate_window(bucket[:acc], bucket[:seen], summary, events)
         end
@@ -99,10 +107,27 @@ module Sentiero
 
       def finalize(acc, seen_sessions, scan_cap, overlay:)
         tally_entries(acc, seen_sessions)
+        collect_store_aggregates(acc, scan_cap) if store.supports_event_aggregates?
         overlay_truncated = overlay ? collect_server_overlay(acc) : false
         ResultBuilder.new(store).build(acc, seen_sessions.size, scan_cap, overlay_truncated)
       end
 
+      def scan_types
+        store.supports_event_aggregates? ? SCAN_TYPES : nil
+      end
+
+      # The figures SCAN_TYPES hides from the scan, recomputed payload-free by
+      # the store. The nil bucket (non-integer client types) counts toward the
+      # total but not the histogram.
+      def collect_store_aggregates(acc, scan_cap)
+        type_counts = store.event_type_counts(limit: scan_cap, since: acc.since, until_time: acc.until_time)
+        type_counts.each { |type, count| acc.event_types[type] = count if type }
+        acc.total_events = type_counts.values.sum
+
+        store.event_counts_by_day(limit: scan_cap, since: acc.since, until_time: acc.until_time)
+          .each { |day, count| acc.per_day_events[day] = count }
+      end
+
       # range_days - 1: the start day is itself one of the range_days buckets.
       def default_since(range_days, until_time)
         end_date = (until_time ? Time.at(until_time) : Time.now).utc.to_date
@@ -115,6 +140,7 @@ module Sentiero
       # methods rather than string-typed acc.key lookups.
       Accumulator = Struct.new(
         :event_types, :custom_tags, :browser_tags, :browsers, :devices,
+        :countries, :cities,
         :entry_pages, :entry_page_errors, :referrers, :duration_buckets,
         :total_events, :durations, :since, :until_time,
         :per_day_events, :per_day_sessions, :per_day_errors, :per_day_tags,
@@ -130,6 +156,8 @@ module Sentiero
           browser_tags: Hash.new(0),
           browsers: Hash.new(0),
           devices: Hash.new(0),
+          countries: Hash.new(0),
+          cities: Hash.new(0),
           entry_pages: Hash.new(0),
           entry_page_errors: Hash.new(0),
           referrers: Hash.new(0),
@@ -166,6 +194,7 @@ module Sentiero
         }
 
         tally_browser_device(acc, metadata["userAgent"])
+        tally_geo(acc, metadata)
         acc.sessions_with_errors += 1 if metadata["has_errors"]
 
         tally_metadata(acc, metadata)
@@ -199,14 +228,17 @@ module Sentiero
       end
 
       def collect_events(acc, events)
+        aggregates_native = store.supports_event_aggregates?
         events.each do |event|
           next unless in_window?(acc, event["timestamp"])
 
           type = event["type"]
-          acc.event_types[type] += 1
-          acc.total_events += 1
+          unless aggregates_native
+            acc.event_types[type] += 1
+            acc.total_events += 1
+            record_event_day(acc, event)
+          end
           tally_custom_tag(acc, event) if type == CUSTOM
-          record_event_day(acc, event)
           record_error_day(acc, event) if error_event?(event)
         end
       end
@@ -228,6 +260,13 @@ module Sentiero
         acc.devices[device] += 1 if device
       end
 
+      def tally_geo(acc, metadata)
+        country = metadata["geo_country"]
+        city = metadata["geo_city"]
+        bounded_tally(acc.countries, country, MAX_GEO_VALUES) if country.is_a?(String) && !country.empty?
+        bounded_tally(acc.cities, city, MAX_GEO_VALUES) if city.is_a?(String) && !city.empty?
+      end
+
       def tally_custom_tag(acc, event)
         data = event["data"]
         return unless data.is_a?(Hash)

data/lib/sentiero/analytics/web_vitals_analyzer.rb

@@ -25,8 +25,8 @@ module Sentiero
         pages = {} # url => VitalsCollector
         accumulation_capped = false
 
-        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time) do |summary, window_id, events|
-          each_page_segment(events) do |url, segment, anchor|
+        _scanned, hit_cap = scan_sessions(limit: limit, since: since, until_time: until_time, types: [META, CUSTOM]) do |summary, window_id, events|
+          each_page_segment(events, anchor: window_anchor(summary, window_id, events)) do |url, segment, anchor|
             next unless url
 
             collector = collector_for(pages, url)

data/lib/sentiero/configuration.rb

@@ -4,6 +4,10 @@ module Sentiero
   class Configuration
     attr_reader :store
 
+    # Reader-only: mutate via #register / #default_platform=, not by
+    # replacing the whole object.
+    attr_reader :fingerprint
+
     attr_accessor :cors_origins,
       :auth_callback,
       :flush_interval_ms,
@@ -54,6 +58,12 @@ module Sentiero
     # logic), so they're declared separately from the plain attr_accessor list.
     attr_reader :session_idle_timeout, :session_max_age
 
+    attr_reader :max_body_size
+
+    # Geo headers are trivially spoofable unless actually behind the CDN, so
+    # trusting them is an explicit opt-in.
+    attr_reader :geo_source
+
     ENFORCED_PRIVACY = {
       maskInputOptions: {password: true}
     }.freeze
@@ -63,6 +73,7 @@ module Sentiero
     # keeps the identifier from living forever on never-idle tabs.
     DEFAULT_SESSION_IDLE_TIMEOUT = 6 * 60 * 60
     DEFAULT_SESSION_MAX_AGE = 7 * 24 * 60 * 60
+    DEFAULT_MAX_BODY_SIZE = 524_288 # 512 KB
 
     # Composition root for store caps: a store assigned to the configuration is
     # bound to the configuration's caps here, so the store itself never reads
@@ -104,6 +115,21 @@ module Sentiero
       @session_max_age = clamp_positive_seconds(value, DEFAULT_SESSION_MAX_AGE)
     end
 
+    # Byte cap on ingest request bodies, raw and gunzipped (dense DOMs can
+    # push FullSnapshots past the default). No "unlimited" setting: the cap
+    # is the gzip-bomb bound and each request may allocate ~2x it, so
+    # invalid values fall back to the default.
+    def max_body_size=(value)
+      @max_body_size = (value.is_a?(Numeric) && value.finite? && value > 0) ? value.to_i : DEFAULT_MAX_BODY_SIZE
+    end
+
+    def geo_source=(value)
+      unless value.nil? || value == :cloudflare || value.respond_to?(:call)
+        raise ArgumentError, "geo_source must be nil, :cloudflare, or a #call-able (env -> Hash)"
+      end
+      @geo_source = value
+    end
+
     private def clamp_positive_seconds(value, default)
       (value.is_a?(Numeric) && value.finite? && value > 0) ? value : default
     end
@@ -115,6 +141,7 @@ module Sentiero
       @flush_interval_ms = 10_000
       @flush_event_threshold = 50
       @max_events_per_page = 1_000
+      @max_body_size = DEFAULT_MAX_BODY_SIZE
       @max_problems = 5_000
       @max_server_events = 50_000
       @ingest_keys = {}
@@ -145,7 +172,9 @@ module Sentiero
       @session_idle_timeout = DEFAULT_SESSION_IDLE_TIMEOUT
       @session_max_age = DEFAULT_SESSION_MAX_AGE
       @redaction = Sentiero::Redaction::Config.new
+      @fingerprint = Sentiero::Fingerprint::Config.new
       @anonymize_ip = true
+      @geo_source = nil
       @audit_log = nil
       # Opt-in: a share file is a full session dump leaving the operator's
       # infrastructure, so export/import routes 404 until explicitly enabled.

data/lib/sentiero/fingerprint/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Sentiero
+  module Fingerprint
+    # Registry of per-platform frame normalizers, reached as
+    # `Sentiero.configuration.fingerprint`. `ErrorsApp` resolves an incoming
+    # occurrence's optional "platform" tag against this registry to pick the
+    # normalizer passed to Fingerprint.compute.
+    class Config
+      attr_accessor :default_platform
+
+      def initialize
+        @normalizers = {}
+        @default_platform = "ruby"
+        register("ruby", RUBY_NORMALIZER)
+        register("crystal", CRYSTAL_NORMALIZER)
+        register("generic", GENERIC_NORMALIZER)
+      end
+
+      # Registering an existing name overrides it, so operators may replace a
+      # built-in (e.g. swap out "ruby") as well as add new platforms.
+      def register(name, callable)
+        @normalizers[name.to_s] = callable
+      end
+
+      # Three-tier resolution (see design doc): a reporter that never learned
+      # about the "platform" field must keep grouping exactly as before
+      # (absent/blank -> default_platform's normalizer, tier 1), whereas a
+      # reporter that declares a platform we don't recognize should not have a
+      # foreign grammar mis-applied to it (unregistered -> generic, tier 3).
+      def resolve(platform)
+        if platform.nil? || platform.to_s.strip.empty?
+          @normalizers.fetch(default_platform.to_s, RUBY_NORMALIZER)
+        else
+          @normalizers.fetch(platform.to_s, GENERIC_NORMALIZER)
+        end
+      end
+    end
+  end
+end