@iann29/rastro 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -4,7 +4,7 @@
 
 Privacy-first, real-time web analytics built as an isolated Convex component.
 
-Amage Rastro combines a 1,000-byte gzip browser tracker with reactive traffic
+Amage Rastro combines a 1.1 KB gzip browser tracker with reactive traffic
 metrics, a live visitor atlas, journey timelines, trusted payment attribution,
 goals, funnels, affiliates, and multi-site reports. Data and functions stay
 inside your Convex deployment.
@@ -27,26 +27,32 @@ Public integration documentation is available at
 should start with [`llms.txt`](https://www.amagerastro.com/llms.txt) and verify
 the [machine manifest](https://www.amagerastro.com/agent/manifest.json).
 
-Current evidence supports more than 120 million stored events/day for realistic
-traffic. Near-limit heavy payloads are certified at 76.62 million/day, and the
-feature-saturated profile at 33.22 million/day. Workload-specific results and
-caveats are reported separately rather than collapsed into one capacity claim.
+Current evidence supports more than 140 million stored events/day for realistic
+traffic and more than 178 million for lean traffic. Near-limit heavy payloads
+are certified at 55.26 million/day on a data-heavy store (76.62 million/day on a
+fresh store, 2026-08-22). The feature-saturated profile currently fails
+certification on a known rollup-contention defect
+([#52](https://github.com/amageweb/amage-rastro/issues/52)). Workload-specific
+results and caveats are reported separately rather than collapsed into one
+capacity claim.
 
 ## What ships
 
-| Capability                  | Implementation                                                                                       |
-| --------------------------- | ---------------------------------------------------------------------------------------------------- |
-| Live visitor map            | Reactive live sessions with coarse city-level coordinates and TTL expiry                             |
-| Traffic analytics           | Sharded hour/day rollups, time series, top pages, sources, countries, devices, browsers, and events  |
-| Journey replay              | Bounded pageview/click/custom-event timelines; no DOM, keystroke, or form-value recording            |
-| Payment conversion tracking | Trusted server-side ledger with idempotent event IDs and canonical site currency                     |
-| Goals and funnels           | Exact pageview/custom-event goals and ordered conversion funnels                                     |
-| Affiliates                  | Referral attribution, trusted revenue, and commission accounting                                     |
-| Cross-site analytics        | Reports over up to ten authorized site IDs with a preloaded pseudonymous visitor ID                  |
-| Automatic GeoIP             | Opt-in native request metadata plus IPinfo/IPWhois fallback; bounded quota and no raw-IP persistence |
-| Auto-captured clicks        | Anchors, buttons, outbound links, and explicit `data-rastro-event` controls                          |
-| Cookieless mode             | Session-scoped pseudonymous IDs in `sessionStorage`; no cookies                                      |
-| Tiny tracker                | 1,846 bytes raw, 1,000 bytes gzip; the test suite enforces `< 1,024` bytes                           |
+| Capability                  | Implementation                                                                                           |
+| --------------------------- | -------------------------------------------------------------------------------------------------------- |
+| Live visitor map            | Reactive live sessions with coarse city-level coordinates and TTL expiry                                 |
+| Traffic analytics           | Sharded hour/day rollups, time series, top pages, sources, countries, devices, browsers, and events      |
+| Field Web Vitals            | Opt-in tracker module reporting LCP, CLS, INP, FCP, and TTFB into bounded per-page daily histograms      |
+| Journey replay              | Bounded pageview/click/custom-event timelines; no DOM, keystroke, or form-value recording                |
+| Payment conversion tracking | Trusted server-side ledger with idempotent event IDs and canonical site currency                         |
+| Goals and funnels           | Exact pageview/custom-event goals and ordered conversion funnels                                         |
+| Affiliates                  | Referral attribution, trusted revenue, and commission accounting                                         |
+| Cross-site analytics        | Reports over up to ten authorized site IDs with a preloaded pseudonymous visitor ID                      |
+| Automatic GeoIP             | Opt-in native request metadata plus IPinfo/IPWhois fallback; bounded quota and no raw-IP persistence     |
+| Auto-captured clicks        | Anchors, buttons, and `data-rastro-event` controls with a bounded visible label; outbound origin+path    |
+| Bot filtering               | Self-declared crawlers, unfurlers, monitors, HTTP libraries, and headless browsers rejected at ingestion |
+| Cookieless mode             | Session-scoped pseudonymous IDs in `sessionStorage`; no cookies                                          |
+| Tiny tracker                | 2,132 bytes raw, 1,127 bytes gzip; the test suite enforces `< 1,280` bytes gzip                          |
 
 ## Quickstart
 
@@ -89,11 +95,12 @@ app.use(rastro, { httpPrefix: "/rastro/" });
 export default app;
 ```
 
-This creates isolated component tables and four HTTP routes:
+This creates isolated component tables and five HTTP routes:
 
 - `POST /rastro/events` — browser event ingestion
 - `OPTIONS /rastro/events` — CORS preflight
 - `GET /rastro/tracker.js` — the pre-gzipped tracker
+- `GET /rastro/vitals.js` — the pre-gzipped, opt-in Web Vitals module
 - `GET /rastro/health` — integration health
 
 Push the component and regenerate host bindings before importing
@@ -175,6 +182,40 @@ the internal `geo:probe` action. If health reports no usable client IP, use
 trusted Vercel/Cloudflare geographic headers with `RASTRO_TRUST_PROXY` or fix
 the deployment's proxy forwarding.
 
+### Browser and device classification
+
+The tracker sends no client identification. Ingestion derives `browser`, `os`,
+and `device` from headers the browser attaches itself, and persists only those
+three normalized values; the raw `User-Agent` never reaches a mutation or a
+component table.
+
+Chromium attaches the low-entropy `Sec-CH-UA`, `Sec-CH-UA-Mobile`, and
+`Sec-CH-UA-Platform` client hints to cross-origin requests from secure origins,
+with no `Accept-CH` opt-in required of the tracked site. They are preferred when
+present, because they are the only signal separating Brave, Opera, Vivaldi,
+Samsung Internet, Yandex, and bare Chromium from Chrome: Brave ships Chrome's
+`User-Agent` verbatim by design. Hint brands are allowlisted, so an unrecognized
+or forged brand falls back to the `User-Agent` instead of entering the browser
+dimension verbatim.
+
+The `User-Agent` remains the fallback for Firefox and Safari, which implement no
+client hints, and for insecure origins, which receive none. Known limits of that
+path:
+
+- iPadOS 13+ requests sites with a Macintosh `User-Agent` by default and Safari
+  sends no hints, so those sessions are reported as desktop macOS.
+- Without hints every Android client is reported as mobile;
+  `Sec-CH-UA-Mobile: ?0` on the Android platform is the only available tablet
+  signal, because the explicit `Sec-CH-UA-Form-Factors` hint is high entropy and
+  would require an `Accept-CH` opt-in and a permissions-policy delegation from
+  every tracked site.
+- Known bots are rejected at ingestion by `User-Agent`: self-declared crawlers,
+  link unfurlers, uptime monitors, HTTP libraries, headless browsers, and any
+  agent carrying a URL. The response keeps the usual counters with `rejected`
+  set and adds `X-Rastro-Rejected: bot`; overview metadata reports
+  `botDetection` as `userAgent`. A scripted browser that spoofs a stock
+  `User-Agent` is still counted as an ordinary session.
+
 ### 3. Create a site
 
 Components cannot read the host app's authentication state. The host must
@@ -264,6 +305,29 @@ serves the script and ingestion from different origins:
 ></script>
 ```
 
+### Field Web Vitals (optional)
+
+A second, separate module measures real-visitor LCP, CLS, INP, FCP, and TTFB
+with `PerformanceObserver` and reports them once per page load, when the tab is
+first hidden. It stays out of `tracker.js` so the base tracker keeps its byte
+budget; add it only where you want performance data:
+
+```html
+<script
+  defer
+  data-site="YOUR_SITE_ID"
+  src="https://YOUR_DEPLOYMENT.convex.site/rastro/vitals.js"
+></script>
+```
+
+The module shares the tracker's session identity through `sessionStorage`,
+accepts the same `data-endpoint` and `data-visitor` overrides, and works with or
+without the base tracker on the page. Measurements are attributed to the landing
+path of the page load, never to later SPA routes. Vitals feed only the
+`vitalsReport` histograms — analytics event counts, sessions, and live presence
+do not change. Browsers without an entry type simply skip that metric (Safari
+reports no LCP, CLS, or INP).
+
 ### React
 
 React is an optional peer dependency. It is required only when importing the
@@ -332,6 +396,12 @@ For declarative click capture:
 </button>
 ```
 
+Auto-captured clicks record the control's visible text, bounded to 64 characters
+and whitespace-normalized, so journeys read "Clicked «View pricing»" without
+annotation. `data-rastro-label` replaces that text; use it on controls whose
+copy may contain personal data. Input values are never read. Outbound links keep
+their origin and pathname; internal links keep the pathname.
+
 Properties accept bounded string, number, boolean, or null values. Never send
 emails, names, form values, secrets, or other personal data as analytics
 properties.
@@ -342,6 +412,46 @@ session or with a timestamp in another minute is allowed. The tracker preserves
 timestamps when retrying. Trusted payment event IDs remain separately
 payload-bound by the site's financial ledger.
 
+## Attribute campaigns
+
+The tracker reads `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, and
+`utm_content` from the landing URL, keeps them in `sessionStorage` for the rest
+of the session, and sends them as properties of every pageview; no other query
+parameter ever leaves the page. A session's `source` is the lowercase
+`utm_source` when present and the referrer host otherwise, so campaign traffic
+no longer reads as `direct`. `utmSource`, `utmMedium`, and `utmCampaign` stay on
+the session for journeys, and `overview.topCampaigns` ranks `utm_campaign` by
+event volume next to `topSources`.
+
+## Identify visitors after signup
+
+Anonymous sessions carry a random `visitorId` until the host supplies a
+pseudonymous one through `data-visitor` or the `RastroScript` `visitorId` prop.
+To keep the anonymous history when a visitor creates an account or signs in,
+link the two ids from the trusted server path, never from the browser:
+
+```js
+const { visitorId: anonymousVisitorId } = window.rastro("context");
+// Send anonymousVisitorId with the signup or sign-in request.
+```
+
+```ts
+await analytics.linkVisitor(ctx, {
+  siteId,
+  visitorId: user.analyticsId, // the value later passed to the tracker
+  previousVisitorId: anonymousVisitorId,
+});
+```
+
+`visitorJourney` for either id then returns one chronological journey; every
+event keeps the id it was recorded with. Links are idempotent, an anonymous id
+belongs to at most one identity, a linked id cannot be linked again, chains and
+identity merges are rejected, and an identity holds at most ten aliases. The
+tracker still sets no cookie: the host's own session identifies the account and
+the anonymous id lives only in `sessionStorage`. Linking anonymous history to an
+account turns it into personal data under the host's privacy policy; disclose it
+and offer an opt-out.
+
 ## Attribute trusted payments
 
 Browser-created conversion events are untrusted telemetry and never affect
@@ -428,8 +538,8 @@ functions.
 
 ### Federated dashboard backend
 
-The reference control plane in `example/` can connect a central dashboard while
-telemetry remains in the customer's deployment. It uses
+The reference control plane in `control-plane/` can connect a central dashboard
+while telemetry remains in the customer's deployment. It uses
 `exposeFederatedAnalyticsApi` with issuer and connection-resolver options. The
 helper constructs its authorization boundary internally; it cannot accept a
 permissive host authorizer. Its surface contains a public protocol v1 manifest,
@@ -455,7 +565,7 @@ runbook.
 The `Rastro` class wraps the component boundary for host functions:
 
 - Sites: `createSite`, `updateSite`, `getSite`, `listSites`
-- Ingestion: `ingest`, `trackConversion`
+- Ingestion: `ingest`, `trackConversion`, `linkVisitor`
 - Reports: `overview`, `liveVisitors`, `listSessions`, `sessionJourney`,
   `listConversions`, `visitorJourney`, `goalsReport`, `funnelsReport`,
   `affiliatesReport`, `dataCoverage`
@@ -472,10 +582,15 @@ cost stays constant instead of increasing with an offset.
 
 Overview responses label visitor values as either HLL-estimated unique visitors
 or legacy `bucketOccurrences`; legacy aggregate rows are never presented as
-exact uniques. Breakdown metadata likewise identifies page, source, country,
-device, browser, and event rankings as event-volume counts. Feature status is
-explicit: outbound-link event volume is supported, while session replay, error
-insights, and bot detection are currently unsupported.
+exact uniques. Anonymous sessions from the same device and network within one
+UTC day count as one visitor through a salted daily key, so cookieless visitor
+counts no longer collapse into session counts; runtimes without a client IP fall
+back to one visitor per session, which `/rastro/health` reports as
+`uniqueVisitors: "session"` instead of `"dailyHash"`. Breakdown metadata
+likewise identifies page, source, country, device, browser, and event rankings
+as event-volume counts. Feature status is explicit: outbound-link event volume
+is supported, bot detection rejects self-declared agents by `User-Agent`, and
+session replay and error insights are currently unsupported.
 
 All report ranges use integer Unix milliseconds with inclusive `from` and `to`
 boundaries. Range metadata reports `boundary: "inclusive"` and
@@ -504,6 +619,10 @@ boundaries use different bucket alignment.
 - Events per batch: 50
 - Session-minute groups per batch: 4
 - Active goals per exact matcher: 1
+- Web Vitals pages per site and UTC day: 48 tracked page rows, then `(other)`;
+  device classes are fixed (desktop, mobile, tablet, unknown)
+- Web Vitals report: complete reads bounded to 5,000 rollup rows across at most
+  90 UTC days; wider saturated ranges fail with `REPORT_INCOMPLETE`
 - Primary aggregate shards: 256 hourly and 128 daily, derived from stable
   session identity
 - Funnel and affiliate aggregate shards: 16
@@ -533,31 +652,42 @@ separately. The browser `feature` profile exercises configured goals, funnels,
 and affiliate attribution; trusted conversions require a separate server-side
 driver and certification result.
 
-### Historical ingest evidence requiring recertification
+### Certified ingest evidence (2026-08-30)
 
 | Profile   | Workload                                          | Certified stored/day | p95 latency | 100M/day target |
 | --------- | ------------------------------------------------- | -------------------: | ----------: | --------------- |
-| Lean      | Minimal events, maximum batches                   |              136.65M |    4,543 ms | Pass            |
-| Realistic | Reused sessions, browser mix, context, heartbeats |              120.81M |    4,247 ms | Pass            |
-| Heavy     | 62 KiB requests with bounded custom properties    |               76.62M |    3,670 ms | Below target    |
-| Feature   | Goals, funnels, and affiliate attribution         |               33.22M |    6,226 ms | Below target    |
-
-Every listed run lasted at least ten minutes, completed with zero request
-failures, duplicates, or rejected events, and exactly reconciled the expected
-stored events. Results came from one client process against a non-production
-Synapse DEV deployment; they are engineering evidence, not a production SLA. The
-heavy row is the formal recertification after removing redundant payload
-serialization. GeoIP with a provider enabled and trusted server-side conversions
-remain separate pending certifications.
-
-These runs predate the current source-derived coverage and recurring-retention
-changes. They remain historical evidence for the named revisions and profiles,
-not certification of this uncommitted implementation. Recertify the final code
-before presenting any row as current capacity.
-
-The latest formal results are recorded in
-[`docs/benchmarks/2026-08-21-formal-certification.md`](docs/benchmarks/2026-08-21-formal-certification.md).
-Earlier development evidence remains available in
+| Lean      | Minimal events, maximum batches                   |              178.95M |    4,167 ms | Pass            |
+| Realistic | Reused sessions, browser mix, context, heartbeats |              142.04M |    4,953 ms | Pass            |
+| Heavy     | 62 KiB requests with bounded custom properties    |               55.26M |    7,702 ms | Below target    |
+| Feature   | Goals, funnels, and affiliate attribution         |           **failed** |           — | Defect [#52]    |
+
+[#52]: https://github.com/amageweb/amage-rastro/issues/52
+
+Lean, realistic, and heavy each ran at least ten minutes, completed with zero
+request failures, duplicates, or rejected events, and exactly reconciled the
+expected stored events (the realistic run's reconciliation was re-executed
+exactly after a client-side DNS failure — see the report). The realistic row's
+driver session pool is 4,096: at current speed the historical 2,048-session pool
+pushes single sessions past the documented 120 events/minute budget. Results
+came from one client process against the same non-production Synapse DEV
+deployment and site as the 2026-08-21 certification; they are engineering
+evidence, not a production SLA.
+
+Two caveats stand deliberately. The heavy row measured a store already holding
+the battery's own multi-million-event history; the 2026-08-22 fresh-store result
+(76.62M/day) remains valid for that state, and neither number overwrites the
+other. The feature profile cannot currently be certified at all: affiliate
+daily-rollup contention loses ~4–5% of batches under concurrent load
+([#52](https://github.com/amageweb/amage-rastro/issues/52)), so no
+feature-profile capacity is claimed until the fix lands. GeoIP with a provider
+enabled, trusted server-side conversions, and vitals-bearing traffic remain
+separate pending certifications.
+
+The full evidence is recorded in
+[`docs/benchmarks/2026-08-30-alpha6-recertification.md`](docs/benchmarks/2026-08-30-alpha6-recertification.md).
+Prior results remain in
+[`docs/benchmarks/2026-08-21-formal-certification.md`](docs/benchmarks/2026-08-21-formal-certification.md)
+and
 [`docs/benchmarks/2026-08-20-realistic.md`](docs/benchmarks/2026-08-20-realistic.md).
 
 From a repository checkout, run a duration-based profile against a confirmed
@@ -637,15 +767,26 @@ Amage Rastro's default tracker:
 - sets no cookies;
 - stores a pseudonymous session ID and referral slug in `sessionStorage`;
 - never persists raw visitor IP addresses in component tables;
+- counts anonymous unique visitors through a salted hash of the request IP and
+  `User-Agent` that rotates every UTC day, derived in the HTTP action from a
+  per-deployment secret; a host-supplied `visitorId` always takes precedence,
+  and the raw IP never reaches a mutation or a table;
+- never persists the raw `User-Agent`, only a normalized browser, operating
+  system, and device;
 - processes an IP only when an edge supplies geography or an operator enables a
   GeoIP provider, which receives that IP under its own privacy terms;
 - stores only country, city, and coordinates rounded to one decimal place;
-- does not record the DOM, screenshots, keystrokes, form values, or arbitrary
-  page text;
-- captures only bounded paths, explicit properties, button/anchor targets, and
-  outbound pathnames;
+- does not record the DOM, screenshots, keystrokes, form values, input contents,
+  or arbitrary page text;
+- captures only bounded paths, explicit properties, the visible label of a
+  clicked link or button (at most 64 characters, replaced by `data-rastro-label`
+  when present), and outbound link origins and pathnames;
 - strips query strings and fragments from stored paths and links.
 
+The optional Web Vitals module inherits this contract: it reports at most five
+timing numbers per page load (milliseconds, or CLS scaled by 1000) against the
+landing path, and nothing else.
+
 Cookieless does not automatically mean consent-exempt in every jurisdiction.
 Review your collection purpose, custom properties, identity strategy, retention
 policy, and local law.
@@ -666,6 +807,10 @@ synapse dev --once
 npm run dev:frontend
 ```
 
+The root `convex.json` targets the control plane in `control-plane/convex`. The
+reference consumer host in `example/` is a separate Convex app; see
+[`example/README.md`](example/README.md) to run, seed, and pair it.
+
 Quality gates:
 
 ```bash
@@ -683,11 +828,13 @@ affiliate commission, cross-site journeys, keyset pagination beyond 1,000 rows,
 retention, request metadata and GeoIP, exact byte boundaries, HTTP routes, React
 integration, and tracker size/behavior.
 
-## Synapse demo
+## Synapse deployments
 
-The active private development project is `ianProjects / Rastro Analytics`. The
-public-facing site URL is resolved from `.env.local`; credentials and
-`.synapse/` are gitignored.
+The repository root is linked to the private Synapse project whose DEV and PROD
+deployments run the control plane in `control-plane/`. The public-facing site
+URL is resolved from `.env.local`; credentials and `.synapse/` are gitignored.
+The consumer host in `example/` is a separate Convex app with its own deployment
+link; run its CLI commands from that directory.
 
 ## License
 

package/agent/integration.md

@@ -470,6 +470,7 @@ export const {
   goalsReport,
   funnelsReport,
   affiliatesReport,
+  vitalsReport,
   dataCoverage,
 } = federated;
 ```
@@ -479,21 +480,22 @@ requires both a valid JWT and a matching, non-revoked local grant.
 
 ## Function contract
 
-| Function           | Input summary                                           | Important output/behavior                                       |
-| ------------------ | ------------------------------------------------------- | --------------------------------------------------------------- |
-| `manifest`         | `{}`                                                    | Static protocol, capabilities, names, and limits; no auth       |
-| `connectionStatus` | `{}`                                                    | Redacted status, protocol version, capabilities, site count     |
-| `listSites`        | `{}`                                                    | Only `siteId`, `name`, `currency`, `timezone`, `cookieless`     |
-| `overview`         | `siteIds`, `from`, `to`, optional hour/day interval     | Aggregate metrics and time series                               |
-| `liveVisitors`     | `siteIds`, `now`, optional limit                        | At most 500 current visitors                                    |
-| `listSessions`     | one `siteId`, range, `{numItems,cursor}` keyset options | Paginated sessions                                              |
-| `sessionJourney`   | one site/session, range, `{numItems,cursor}` options    | Paginated bounded events                                        |
-| `listConversions`  | one site, range, `{numItems,cursor}` options            | Paginated trusted server-side conversion ledger                 |
-| `visitorJourney`   | site IDs, visitor ID, range, optional limit             | Cross-site journey inside the grant only                        |
-| `goalsReport`      | one site and range                                      | Read-only goal definitions plus aggregates                      |
-| `funnelsReport`    | one site and complete UTC-day range                     | Read-only definitions/steps plus aggregates; max 90 days        |
-| `affiliatesReport` | one site and complete UTC-day range                     | Read-only affiliate definitions plus aggregates                 |
-| `dataCoverage`     | one site and inclusive integer range                    | Coverage metadata; echoes site ID, no event/visitor/session IDs |
+| Function           | Input summary                                           | Important output/behavior                                        |
+| ------------------ | ------------------------------------------------------- | ---------------------------------------------------------------- |
+| `manifest`         | `{}`                                                    | Static protocol, capabilities, names, and limits; no auth        |
+| `connectionStatus` | `{}`                                                    | Redacted status, protocol version, capabilities, site count      |
+| `listSites`        | `{}`                                                    | Only `siteId`, `name`, `currency`, `timezone`, `cookieless`      |
+| `overview`         | `siteIds`, `from`, `to`, optional hour/day interval     | Aggregate metrics and time series                                |
+| `liveVisitors`     | `siteIds`, `now`, optional limit                        | At most 500 current visitors                                     |
+| `listSessions`     | one `siteId`, range, `{numItems,cursor}` keyset options | Paginated sessions                                               |
+| `sessionJourney`   | one site/session, range, `{numItems,cursor}` options    | Paginated bounded events                                         |
+| `listConversions`  | one site, range, `{numItems,cursor}` options            | Paginated trusted server-side conversion ledger                  |
+| `visitorJourney`   | site IDs, visitor ID, range, optional limit             | Cross-site journey inside the grant only                         |
+| `goalsReport`      | one site and range                                      | Read-only goal definitions plus aggregates                       |
+| `funnelsReport`    | one site and complete UTC-day range                     | Read-only definitions/steps plus aggregates; max 90 days         |
+| `affiliatesReport` | one site and complete UTC-day range                     | Read-only affiliate definitions plus aggregates                  |
+| `vitalsReport`     | one site and complete UTC-day range                     | Web Vitals p75/ratings per metric, page, and device; max 90 days |
+| `dataCoverage`     | one site and inclusive integer range                    | Coverage metadata; echoes site ID, no event/visitor/session IDs  |
 
 The federated surface deliberately excludes ingestion, site mutation, retention
 writes, configuration writes, domains, owner IDs, network IDs, and arbitrary

package/agent/manifest.json

@@ -15,9 +15,9 @@
     "upgrading": "https://www.amagerastro.com/docs/reference/upgrading.md",
     "integrity": {
       "algorithm": "sha256",
-      "agent": "711faf2ca11ee22432cb8b51c7f64fb7e25045a6509391fc8532f08b2fdf3e11",
+      "agent": "e2faf12674afb40409c268048595856a248d4a4373af4c7a013089364fc9f28b",
       "llms": "8c1da1fea23f95a618c4d636840b793195fceedf05f81394df74e1ed5e3fc4da",
-      "protocol": "6d15aa19469d1e5e008949f1f42417875137ba040bb2bf4427841a5aa0caea77",
+      "protocol": "3a5cba45befc3ff0b56828cb207d8ce67ddc0df6bf0280a977d4db8d7f50aaee",
       "setup": "04c61ecef029a99ba95e1002439dbd1e42ca1ce351e6deb0988fb556ffce649e",
       "upgrading": "9ff81b8a5e4a615e284916aeae8c7602f3249093599f60b97066a614db406c5a"
     }
@@ -67,7 +67,8 @@
       "goalsReport": "goalsReport",
       "funnelsReport": "funnelsReport",
       "affiliatesReport": "affiliatesReport",
-      "dataCoverage": "dataCoverage"
+      "dataCoverage": "dataCoverage",
+      "vitalsReport": "vitalsReport"
     },
     "capabilities": [
       "siteSummaries",
@@ -80,7 +81,8 @@
       "goals",
       "funnels",
       "affiliates",
-      "dataCoverage"
+      "dataCoverage",
+      "vitals"
     ],
     "limits": {
       "maxSitesPerRequest": 10,

package/agent/manifest.schema.json

@@ -167,7 +167,8 @@
             "goalsReport",
             "funnelsReport",
             "affiliatesReport",
-            "dataCoverage"
+            "dataCoverage",
+            "vitalsReport"
           ],
           "properties": {
             "manifest": { "const": "manifest" },
@@ -182,14 +183,15 @@
             "goalsReport": { "const": "goalsReport" },
             "funnelsReport": { "const": "funnelsReport" },
             "affiliatesReport": { "const": "affiliatesReport" },
-            "dataCoverage": { "const": "dataCoverage" }
+            "dataCoverage": { "const": "dataCoverage" },
+            "vitalsReport": { "const": "vitalsReport" }
           },
           "additionalProperties": false
         },
         "capabilities": {
           "type": "array",
-          "minItems": 11,
-          "maxItems": 11,
+          "minItems": 12,
+          "maxItems": 12,
           "uniqueItems": true,
           "items": {
             "enum": [
@@ -203,7 +205,8 @@
               "goals",
               "funnels",
               "affiliates",
-              "dataCoverage"
+              "dataCoverage",
+              "vitals"
             ]
           }
         },

package/dist/client/federation.d.ts

@@ -14,6 +14,27 @@ export declare const FEDERATED_ANALYTICS_ERROR_CODES: Readonly<{
     readonly INVALID_SCOPE: "FEDERATION_INVALID_SCOPE";
     readonly SITE_DENIED: "FEDERATION_SITE_DENIED";
 }>;
+/**
+ * The protocol-v1 baseline every compatible host must serve. Newer hosts may
+ * advertise more functions and capabilities; a dashboard must require only
+ * this frozen set, or older hosts would fail verification on every addition.
+ */
+export declare const FEDERATED_ANALYTICS_REQUIRED_FUNCTIONS: Readonly<{
+    readonly manifest: "manifest";
+    readonly connectionStatus: "connectionStatus";
+    readonly listSites: "listSites";
+    readonly overview: "overview";
+    readonly liveVisitors: "liveVisitors";
+    readonly listSessions: "listSessions";
+    readonly sessionJourney: "sessionJourney";
+    readonly listConversions: "listConversions";
+    readonly visitorJourney: "visitorJourney";
+    readonly goalsReport: "goalsReport";
+    readonly funnelsReport: "funnelsReport";
+    readonly affiliatesReport: "affiliatesReport";
+    readonly dataCoverage: "dataCoverage";
+}>;
+export declare const FEDERATED_ANALYTICS_REQUIRED_CAPABILITIES: readonly ["siteSummaries", "overview", "liveVisitors", "sessions", "sessionJourney", "conversions", "visitorJourney", "goals", "funnels", "affiliates", "dataCoverage"];
 export declare const FEDERATED_ANALYTICS_CONNECTOR_MANIFEST: Readonly<{
     readonly protocol: "amage-rastro-analytics";
     readonly protocolVersion: 1;
@@ -32,8 +53,9 @@ export declare const FEDERATED_ANALYTICS_CONNECTOR_MANIFEST: Readonly<{
         readonly funnelsReport: "funnelsReport";
         readonly affiliatesReport: "affiliatesReport";
         readonly dataCoverage: "dataCoverage";
+        readonly vitalsReport: "vitalsReport";
     }>;
-    readonly capabilities: readonly ["siteSummaries", "overview", "liveVisitors", "sessions", "sessionJourney", "conversions", "visitorJourney", "goals", "funnels", "affiliates", "dataCoverage"];
+    readonly capabilities: readonly ["siteSummaries", "overview", "liveVisitors", "sessions", "sessionJourney", "conversions", "visitorJourney", "goals", "funnels", "affiliates", "dataCoverage", "vitals"];
     readonly limits: Readonly<{
         readonly maxSitesPerRequest: 10;
         readonly maxSitesPerConnection: 10;
@@ -75,7 +97,7 @@ export interface FederatedAnalyticsAuthorizerOptions {
     resolveConnection: ResolveFederatedAnalyticsConnection;
 }
 export declare const federatedAnalyticsManifestValidator: import("convex/values").VObject<{
-    capabilities: ("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney")[];
+    capabilities: ("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals")[];
     functions: {
         affiliatesReport: "affiliatesReport";
         connectionStatus: "connectionStatus";
@@ -90,6 +112,7 @@ export declare const federatedAnalyticsManifestValidator: import("convex/values"
         overview: "overview";
         sessionJourney: "sessionJourney";
         visitorJourney: "visitorJourney";
+        vitalsReport: "vitalsReport";
     };
     limits: {
         maxJourneyEvents: number;
@@ -119,6 +142,7 @@ export declare const federatedAnalyticsManifestValidator: import("convex/values"
         overview: "overview";
         sessionJourney: "sessionJourney";
         visitorJourney: "visitorJourney";
+        vitalsReport: "vitalsReport";
     }, {
         manifest: import("convex/values").VLiteral<"manifest", "required">;
         connectionStatus: import("convex/values").VLiteral<"connectionStatus", "required">;
@@ -133,8 +157,9 @@ export declare const federatedAnalyticsManifestValidator: import("convex/values"
         funnelsReport: import("convex/values").VLiteral<"funnelsReport", "required">;
         affiliatesReport: import("convex/values").VLiteral<"affiliatesReport", "required">;
         dataCoverage: import("convex/values").VLiteral<"dataCoverage", "required">;
-    }, "required", "affiliatesReport" | "connectionStatus" | "dataCoverage" | "funnelsReport" | "goalsReport" | "listConversions" | "listSessions" | "listSites" | "liveVisitors" | "manifest" | "overview" | "sessionJourney" | "visitorJourney">;
-    capabilities: import("convex/values").VArray<("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney")[], import("convex/values").VUnion<"affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney", [import("convex/values").VLiteral<"siteSummaries", "required">, import("convex/values").VLiteral<"overview", "required">, import("convex/values").VLiteral<"liveVisitors", "required">, import("convex/values").VLiteral<"sessions", "required">, import("convex/values").VLiteral<"sessionJourney", "required">, import("convex/values").VLiteral<"conversions", "required">, import("convex/values").VLiteral<"visitorJourney", "required">, import("convex/values").VLiteral<"goals", "required">, import("convex/values").VLiteral<"funnels", "required">, import("convex/values").VLiteral<"affiliates", "required">, import("convex/values").VLiteral<"dataCoverage", "required">], "required", never>, "required">;
+        vitalsReport: import("convex/values").VLiteral<"vitalsReport", "required">;
+    }, "required", "affiliatesReport" | "connectionStatus" | "dataCoverage" | "funnelsReport" | "goalsReport" | "listConversions" | "listSessions" | "listSites" | "liveVisitors" | "manifest" | "overview" | "sessionJourney" | "visitorJourney" | "vitalsReport">;
+    capabilities: import("convex/values").VArray<("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals")[], import("convex/values").VUnion<"affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals", [import("convex/values").VLiteral<"siteSummaries", "required">, import("convex/values").VLiteral<"overview", "required">, import("convex/values").VLiteral<"liveVisitors", "required">, import("convex/values").VLiteral<"sessions", "required">, import("convex/values").VLiteral<"sessionJourney", "required">, import("convex/values").VLiteral<"conversions", "required">, import("convex/values").VLiteral<"visitorJourney", "required">, import("convex/values").VLiteral<"goals", "required">, import("convex/values").VLiteral<"funnels", "required">, import("convex/values").VLiteral<"affiliates", "required">, import("convex/values").VLiteral<"dataCoverage", "required">, import("convex/values").VLiteral<"vitals", "required">], "required", never>, "required">;
     limits: import("convex/values").VObject<{
         maxJourneyEvents: number;
         maxLiveVisitors: number;
@@ -148,16 +173,16 @@ export declare const federatedAnalyticsManifestValidator: import("convex/values"
         maxLiveVisitors: import("convex/values").VFloat64<number, "required">;
         maxJourneyEvents: import("convex/values").VFloat64<number, "required">;
     }, "required", "maxJourneyEvents" | "maxLiveVisitors" | "maxReportRangeDays" | "maxSitesPerConnection" | "maxSitesPerRequest">;
-}, "required", "capabilities" | "functions" | "functions.affiliatesReport" | "functions.connectionStatus" | "functions.dataCoverage" | "functions.funnelsReport" | "functions.goalsReport" | "functions.listConversions" | "functions.listSessions" | "functions.listSites" | "functions.liveVisitors" | "functions.manifest" | "functions.overview" | "functions.sessionJourney" | "functions.visitorJourney" | "limits" | "limits.maxJourneyEvents" | "limits.maxLiveVisitors" | "limits.maxReportRangeDays" | "limits.maxSitesPerConnection" | "limits.maxSitesPerRequest" | "moduleName" | "protocol" | "protocolVersion">;
+}, "required", "capabilities" | "functions" | "functions.affiliatesReport" | "functions.connectionStatus" | "functions.dataCoverage" | "functions.funnelsReport" | "functions.goalsReport" | "functions.listConversions" | "functions.listSessions" | "functions.listSites" | "functions.liveVisitors" | "functions.manifest" | "functions.overview" | "functions.sessionJourney" | "functions.visitorJourney" | "functions.vitalsReport" | "limits" | "limits.maxJourneyEvents" | "limits.maxLiveVisitors" | "limits.maxReportRangeDays" | "limits.maxSitesPerConnection" | "limits.maxSitesPerRequest" | "moduleName" | "protocol" | "protocolVersion">;
 export declare const federatedAnalyticsConnectionStatusValidator: import("convex/values").VObject<{
-    capabilities: ("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney")[];
+    capabilities: ("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals")[];
     protocolVersion: 1;
     siteCount: number;
     status: "connected";
 }, {
     status: import("convex/values").VLiteral<"connected", "required">;
     protocolVersion: import("convex/values").VLiteral<1, "required">;
-    capabilities: import("convex/values").VArray<("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney")[], import("convex/values").VUnion<"affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney", [import("convex/values").VLiteral<"siteSummaries", "required">, import("convex/values").VLiteral<"overview", "required">, import("convex/values").VLiteral<"liveVisitors", "required">, import("convex/values").VLiteral<"sessions", "required">, import("convex/values").VLiteral<"sessionJourney", "required">, import("convex/values").VLiteral<"conversions", "required">, import("convex/values").VLiteral<"visitorJourney", "required">, import("convex/values").VLiteral<"goals", "required">, import("convex/values").VLiteral<"funnels", "required">, import("convex/values").VLiteral<"affiliates", "required">, import("convex/values").VLiteral<"dataCoverage", "required">], "required", never>, "required">;
+    capabilities: import("convex/values").VArray<("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals")[], import("convex/values").VUnion<"affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals", [import("convex/values").VLiteral<"siteSummaries", "required">, import("convex/values").VLiteral<"overview", "required">, import("convex/values").VLiteral<"liveVisitors", "required">, import("convex/values").VLiteral<"sessions", "required">, import("convex/values").VLiteral<"sessionJourney", "required">, import("convex/values").VLiteral<"conversions", "required">, import("convex/values").VLiteral<"visitorJourney", "required">, import("convex/values").VLiteral<"goals", "required">, import("convex/values").VLiteral<"funnels", "required">, import("convex/values").VLiteral<"affiliates", "required">, import("convex/values").VLiteral<"dataCoverage", "required">, import("convex/values").VLiteral<"vitals", "required">], "required", never>, "required">;
     siteCount: import("convex/values").VFloat64<number, "required">;
 }, "required", "capabilities" | "protocolVersion" | "siteCount" | "status">;
 export declare const federatedSiteSummaryValidator: import("convex/values").VObject<{
@@ -191,8 +216,9 @@ export declare function createFederatedAnalyticsManifest(): {
         funnelsReport: "funnelsReport";
         affiliatesReport: "affiliatesReport";
         dataCoverage: "dataCoverage";
+        vitalsReport: "vitalsReport";
     };
-    capabilities: ("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney")[];
+    capabilities: ("affiliates" | "conversions" | "dataCoverage" | "funnels" | "goals" | "liveVisitors" | "overview" | "sessionJourney" | "sessions" | "siteSummaries" | "visitorJourney" | "vitals")[];
     limits: {
         maxSitesPerRequest: 10;
         maxSitesPerConnection: 10;