@iann29/rastro 0.1.0-alpha.9 → 0.1.0

package/docs/upgrading.md

@@ -1,23 +1,28 @@
 # Upgrading Amage Rastro
 
-Amage Rastro is pre-stable. Pin exact versions, read the changelog, and rehearse
-upgrades against a non-production snapshot before changing a maintained
-deployment.
+Pin exact versions, read the changelog, and rehearse upgrades against a
+non-production snapshot before changing a maintained deployment. `0.1.0` is the
+first release without a prerelease tag; the alphas below it stay documented for
+hosts still on them.
 
 ## Release matrix
 
-| Current state                                         | Required path                                                                       | Success condition                                                |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| Fresh deployment                                      | Install the intended release directly                                               | Component deploys and `/rastro/health` succeeds                  |
-| `0.1.0-alpha.0` with maintained data                  | Install `0.1.0-alpha.1` first and wait for staged visitor-index backfills           | Every staged index reports complete before installing `alpha.2`  |
-| `0.1.0-alpha.1`                                       | Wait for staged visitor-index backfills, then install `alpha.2`                     | Backfills complete before active readers deploy                  |
-| `0.1.0-alpha.2` with legacy `events` rows             | Stay on `alpha.2` and run/resume migration                                          | Durable success plus empty source                                |
-| `0.1.0-alpha.3` fresh/canonical deployment            | Rehearse the next alpha normally                                                    | Schema, reports, tracker, and retention checks pass              |
-| `0.1.0-alpha.3` through `alpha.5` with canonical data | Install `0.1.0-alpha.6` directly; Web Vitals tables are additive                    | Schema deploys and `/rastro/health` reports `webVitals: "optIn"` |
-| `0.1.0-alpha.6`                                       | Install `0.1.0-alpha.7` directly; no schema change                                  | `GET /rastro/tracker.js` contains `sentAt`                       |
-| `0.1.0-alpha.7`                                       | Install `0.1.0-alpha.8` directly; site map tables are additive; re-export `siteMap` | `/rastro/health` reports `siteMap: "dailyRollup"`                |
-| `0.1.0-alpha.8`                                       | Install `0.1.0-alpha.9` directly; no schema change; the tracker changes             | `/rastro/health` reports `liveDepartures: "leaveBeacon"`         |
-| Any release whose packed declarations lack federation | Stop and request an eligible exact registry release                                 | Packed declarations contain the federation exports               |
+| Current state                                         | Required path                                                                                                                                   | Success condition                                                   |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Fresh deployment                                      | Install the intended release directly                                                                                                           | Component deploys and `/rastro/health` succeeds                     |
+| `0.1.0-alpha.0` with maintained data                  | Install `0.1.0-alpha.1` first and wait for staged visitor-index backfills                                                                       | Every staged index reports complete before installing `alpha.2`     |
+| `0.1.0-alpha.1`                                       | Wait for staged visitor-index backfills, then install `alpha.2`                                                                                 | Backfills complete before active readers deploy                     |
+| `0.1.0-alpha.2` with legacy `events` rows             | Stay on `alpha.2` and run/resume migration                                                                                                      | Durable success plus empty source                                   |
+| `0.1.0-alpha.3` fresh/canonical deployment            | Rehearse the next alpha normally                                                                                                                | Schema, reports, tracker, and retention checks pass                 |
+| `0.1.0-alpha.3` through `alpha.5` with canonical data | Install `0.1.0-alpha.6` directly; Web Vitals tables are additive                                                                                | Schema deploys and `/rastro/health` reports `webVitals: "optIn"`    |
+| `0.1.0-alpha.6`                                       | Install `0.1.0-alpha.7` directly; no schema change                                                                                              | `GET /rastro/tracker.js` contains `sentAt`                          |
+| `0.1.0-alpha.7`                                       | Install `0.1.0-alpha.8` directly; site map tables are additive; re-export `siteMap`                                                             | `/rastro/health` reports `siteMap: "dailyRollup"`                   |
+| `0.1.0-alpha.8`                                       | Install `0.1.0-alpha.10` directly; no schema change; the tracker changes                                                                        | `/rastro/health` reports `liveDepartures: "leaveBeacon"`            |
+| `0.1.0-alpha.9`                                       | Install `0.1.0-alpha.10` directly; `alpha.9` is deprecated — it rejected its own leave beacons                                                  | The final page-close `POST /rastro/events` returns 200              |
+| `0.1.0-alpha.10`                                      | Install `0.1.0-alpha.12` directly; new tables and fields are additive; re-export the configure functions to opt in                              | `/rastro/health` reports `tracker.version: "0.1.0-alpha.12"`        |
+| `0.1.0-alpha.11`                                      | Install `0.1.0-alpha.12` directly; same code, the package now ships `src/tracker/generated.ts`                                                  | A `convex/` test importing `@iann29/rastro/test` typechecks on push |
+| `0.1.0-alpha.12`                                      | Install `0.1.0` directly; every schema change is an optional field or a new table; add `analytics:public` to a grant only to allow public links | `/rastro/health` reports `tracker.version: "0.1.0"`                 |
+| Any release whose packed declarations lack federation | Stop and request an eligible exact registry release                                                                                             | Packed declarations contain the federation exports                  |
 
 Do not upgrade a populated legacy deployment directly to a release that removes
 the `events` table. Schema acceptance alone does not prove that telemetry was
@@ -171,7 +176,14 @@ Acceptance for this upgrade: `/rastro/health` reports
 between two pages, `siteMap` returns both routes and the transition between
 them.
 
-## Realtime presence and persistent identity (alpha.9)
+## Realtime presence and persistent identity (alpha.9, fixed in alpha.10)
+
+**Install `0.1.0-alpha.10`, never `alpha.9`.** As published, `alpha.9`'s HTTP
+action rejected any batch containing the new `leave` event; the final pagehide
+flush carries the whole remaining queue in one body, so outbound clicks and
+pending events were lost on every page close while departures silently fell back
+to the safety net. `alpha.9` is deprecated on npm; `alpha.10` is the same
+release with the event accepted at the boundary.
 
 `0.1.0-alpha.9` changes no schema, but it changes the served tracker twice over,
 so the cache window is the whole upgrade story.
@@ -195,16 +207,135 @@ contract describes what is stored (origin-scoped, never a cookie, gone when the
 visitor clears site data) and the consent note to reconcile with local
 requirements.
 
-**The tracker is cached** (`max-age=300, stale-while-revalidate=86400`): for up
+**The tracker is cached** (`max-age=300, stale-while-revalidate=86400` on hosts
+through `alpha.10`; the stale window shrinks to an hour from `alpha.11`): for up
 to a day after the deploy, returning visitors and already-open tabs run the old
 tracker — per-tab identity, no leave beacon. They degrade cleanly to the
 90-second safety net and to per-tab counting until the cache turns over.
-Validate in a private window, not in a tab that was open during the deploy.
+Validate in a private window, not in a tab that was open during the deploy; see
+[Tracker cache](#tracker-cache).
 
 Acceptance for this upgrade: `/rastro/health` reports
 `features.liveDepartures: "leaveBeacon"`, `GET /rastro/tracker.js` contains
 `leave` and `_rv`, two tabs on the site appear as one active visitor, and
-closing both removes the visitor from **Ao vivo** within seconds.
+closing both removes the visitor from **Ao vivo** within seconds — and the final
+`/rastro/events` beacon on the page close returns 200 in the network log,
+not 400.
+
+## Calendar days in the site's timezone (alpha.11)
+
+`0.1.0-alpha.11` buckets each event once more, by the calendar day of the site's
+timezone (`aggregateBuckets.granularity: "localDay"`), for sites whose timezone
+ever leaves UTC. Nothing is backfilled: coverage starts at the first ingest
+after the upgrade plus the rollup safety delay, stamped as
+`analyticsCoverage.localDaySince`, and restarts when a site's timezone changes.
+Until the stamp covers a dashboard's range and the one before it, the dashboard
+keeps reading whole UTC days, so the switch is silent — the trend chart caption
+says which days a view follows. The `aggregateDay` retention kind now purges the
+local-day buckets alongside the UTC ones. The connector manifest advertises the
+optional `localDays` capability; no host edit is required, since the capability
+adds no function.
+
+## Configure scope (alpha.11)
+
+`0.1.0-alpha.11` changes no component schema. It adds the optional `configure`
+capability to the federated surface: fourteen functions (`siteSettings`,
+`updateSite`, `listGoals`, `upsertGoal`, `removeGoal`, `listFunnels`,
+`upsertFunnel`, `removeFunnel`, `listAffiliates`, `upsertAffiliate`,
+`removeAffiliate`, `retentionStatus`, `setRetentionPolicy`,
+`disableRetentionPolicy`) that let the dashboard's organization owners and
+admins configure a granted site, and the stable error
+`FEDERATION_CONFIGURE_FORBIDDEN`. Nothing runs until the host opts in.
+
+Two host edits are involved, both in the federation module and its grant:
+
+1. `convex/rastroFederation.ts` re-exports the new functions from `federated`
+   (the runbook shows the complete list). As with `siteMap` in `alpha.8`, the
+   connector manifest is static package metadata: it advertises `configure`
+   whether or not the module exports the functions, so a host that later grants
+   the scope without this export leaves every form in the dashboard failing with
+   a missing-function error.
+2. The `rastroFederationGrants` table gains an optional
+   `permissions: v.optional(v.array(v.string()))`, and `provisionConnection`
+   accepts `permissions` validated with `federatedAnalyticsPermissionValidator`.
+   A grant without it stays read only; the resolver passes `grant.permissions`
+   through as `FederatedAnalyticsConnection.permissions`.
+
+Reads are unchanged, and a host that upgrades the package without either edit
+keeps working as a read-only connection. `connectionStatus` now returns the
+effective `permissions`; a dashboard talking to an older host treats the absent
+field as read only. After deploying, open **Conexões** and click **Verificar
+novamente** so the stored capability list picks up `configure` and the card
+reports "Somente leitura" or "Leitura e configuração".
+
+Acceptance for this upgrade: `rastroFederation:manifest` lists the `configure`
+capability; with a read-only grant, `upsertGoal` under a configure-carrying
+identity fails with `FEDERATION_CONFIGURE_FORBIDDEN`; after reprovisioning with
+`"permissions":["analytics:configure"]`, an owner or admin creates a goal from
+**Metas** and `listGoals` returns it, while a member sees only the generated
+code.
+
+## Leaving alpha (0.1.0)
+
+`0.1.0` is the first release without a prerelease tag. An `alpha.12` host
+installs it directly: `sessions` gains an optional `newVisitor`, `liveSessions`
+gains the optional intent fields (`entryPath`, `returning`, `utmCampaign`,
+`affiliateSlug`, `conversionCount`, `funnel`), `aggregateBuckets` slots accept
+the `medium` and `outbound` dimension types, and `analyticsCoverage` gains
+`dimensionsSince`, stamped at each site's first ingest on this version plus the
+rollup delay. No federated function changed its arguments and no re-export is
+needed: `overview` gains `topMediums`, `topOutbound` and
+`metadata.dimensionsSince`, `liveVisitors` gains the intent fields, and
+`listSessions` gains `newVisitor`; a dashboard reading an older host hides what
+it does not receive.
+
+What a host may choose to do:
+
+- **Public links.** A grant that lists `analytics:public` allows the control
+  plane to mint tokens for `#/p/<slug>` pages. Such a token carries
+  `rastro_permissions: ["analytics:public"]` alone and the bounded
+  `rastro_site_ids` claim, may run only `manifest`, `connectionStatus`,
+  `listSites`, `overview`, `liveVisitors` and `dataCoverage`, sees a redacted
+  `overview` (no revenue, conversions, goals, campaigns or custom events) and a
+  `liveVisitors` whose visitor id is the session id. A grant without the
+  permission refuses every public call with `FEDERATION_PUBLIC_FORBIDDEN`; an
+  `alpha.12` host refuses the token with `FEDERATION_INVALID_CLAIMS`. After
+  changing a grant, click "Verificar novamente" in Conexões so the control plane
+  records the permission before it lets a member create a link.
+- **Heat rules.** `visitorHeat` is exported for hosts that want the dashboard's
+  hot/warm/cold score on their own side; it is pure and needs no deploy.
+
+The dashboard's "Meios" and "Destinos externos" cards, the "Quentes agora"
+figure, the "Reprise" in the journey sheet and the `#/telao` board appear as
+soon as the host runs `0.1.0`; a range that starts before `dimensionsSince`
+captions the two new cards with the date the count began.
+
+Control plane deployments: `rastroPublicLinks` is a new table and
+`publicLinks.*` are new functions; deploy `control-plane/convex` before or with
+the dashboard build that links to public pages.
+
+## Tracker cache
+
+`GET /rastro/tracker.js` and `GET /rastro/vitals.js` are served with a
+five-minute fresh window followed by a stale-while-revalidate window: up to a
+day on hosts through `alpha.10`, up to an hour from `alpha.11`. Two consequences
+apply to every release that changes the served script:
+
+- A tab that was open during the deploy never reloads the script. It keeps the
+  previous tracker until the page itself is reloaded.
+- A returning visitor's first page load inside the stale window runs the
+  previous tracker while the browser revalidates in the background; the next
+  load runs the new one.
+
+So a request that still lacks a field the new tracker sends (`sentAt`, `leave`,
+`_rv`) during that window is expected, not evidence of a failed deploy — the
+alpha.5 rehearsal on a real host raised exactly that false alarm. Validate an
+upgrade in a fresh browser context (a private window, or a tab opened after the
+deploy), and inspect `GET /rastro/tracker.js` directly when the served script is
+in doubt. From `alpha.11` both scripts carry a strong `ETag` and answer
+`If-None-Match` with `304`; compare the `ETag` your browser received with
+`tracker.hash` from `/rastro/health`, which the dashboard's **Instalação** view
+also shows.
 
 ## Federation releases
 
@@ -231,14 +362,20 @@ control-plane issuer.
 - DEV or a snapshot-seeded sandbox accepted the schema.
 - Legacy migration status is complete when applicable.
 - Staged indexes completed before their readers were activated.
-- `/rastro/health` succeeds on the HTTP-actions URL.
-- A real tracker request is accepted from an allowed origin.
+- `/rastro/health` succeeds on the HTTP-actions URL and `tracker.version` names
+  the release just installed.
+- A real tracker request is accepted from an allowed origin, observed in a
+  browser context opened after the deploy (see [Tracker cache](#tracker-cache)).
 - When the host opts into Web Vitals: `/rastro/vitals.js` serves and
   `vitalsReport` reflects a real page load.
 - On `alpha.8` or later: the federation module re-exports `siteMap` and, after a
   real two-page visit, `siteMap` returns both routes and their transition.
 - On `alpha.9` or later: closing the site's last tab removes the visitor from
   the live view within seconds, and two tabs count as one visitor.
+- On `alpha.11` or later: the federation module re-exports the configure
+  functions, a read-only grant refuses `upsertGoal` with
+  `FEDERATION_CONFIGURE_FORBIDDEN`, and a grant listing `analytics:configure`
+  lets an owner or admin create a goal from the dashboard.
 - Protected overview, journey, goal, funnel, and affiliate reports used by the
   host still run.
 - Trusted conversion idempotency and currency checks still pass.

package/llms.txt

@@ -1,6 +1,6 @@
 # Amage Rastro
 
-> Privacy-first, real-time web analytics for Convex. Telemetry stays in each product's Convex or Synapse deployment; the central dashboard reads only an explicitly granted, read-only report surface.
+> Privacy-first, real-time web analytics for Convex. Telemetry stays in each product's Convex or Synapse deployment; the central dashboard reads only an explicitly granted report surface, and configures a site only when its host's grant opts into the configure scope.
 
 Canonical documentation: https://www.amagerastro.com/docs/
 Machine manifest: https://www.amagerastro.com/agent/manifest.json
@@ -30,7 +30,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - Resolve an indexed, authoritative local grant on every federated query.
 - Grant one through ten explicit site IDs. Never grant by owner-wide enumeration.
 - Use the canonical module name `convex/rastroFederation.ts`.
-- Expose only the manifest, connection status, site summaries, reports, journeys, conversions, affiliates, funnels, goals, web vitals, and coverage listed in the manifest.
+- Expose only the manifest, connection status, site summaries, reports, journeys, conversions, affiliates, funnels, goals, web vitals, coverage, and the configure functions listed in the manifest; the configure functions run only when the token and the local grant both carry `analytics:configure`. A public link's token carries `analytics:public` alone and reaches only the manifest, connection status, site summaries, a redacted overview, redacted live visitors, and coverage, and only when the local grant lists `analytics:public`.
 - Use the functions URL as JWT audience and the HTTP-actions URL for tracker ingestion.
 - Rehearse on an explicit development target. Production changes require fresh operator consent.
 - Validate manifest, authenticated connection status, redacted site list, real ingestion, reactive live data, and local-first revocation.
@@ -57,15 +57,17 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - Maximum live visitors: 500.
 - Live window: a `leave` beacon on pagehide retires a visitor about ten seconds after they leave, and a bfcache return revives them; the safety net without a goodbye is 90 seconds since the last event or heartbeat. `POST /rastro/events` re-anchors a batch whose `sentAt` is more than 30 seconds from server time, so a wrong device clock decides neither liveness nor hour buckets.
 - Maximum journey events: 500.
-- Token lifetime: 10 minutes, RS256, permission `analytics:read`.
+- Token lifetime: 10 minutes, RS256. Every member's token carries `analytics:read`; owners and admins also carry `analytics:configure`, which the host honors only when the local grant lists it (`configure` is an optional capability that hosts before `alpha.11` do not advertise). A public link's token carries `analytics:public` alone, plus `rastro_site_ids` naming the link's sites; hosts before `0.1.0` reject it.
 
 ## Read semantics
 
 - Times are inclusive Unix epoch milliseconds in UTC.
-- Goal, funnel, and affiliate reports include read-only definitions plus aggregates; configuration writes are not exposed.
+- Goal, funnel, and affiliate reports include read-only definitions plus aggregates. Configuration writes (goals, funnels, affiliates, a site's name/domains/timezone, retention) exist only in the configure scope and fail with `FEDERATION_CONFIGURE_FORBIDDEN` for a read-only token or grant; `listSites` never returns domains, only `siteSettings` does, to a connection allowed to change them.
+- A public token (`analytics:public`) gets `overview` with zero `conversions` and `revenueCents` and empty `topCampaigns`, `topMediums`, `topEvents`, and `topGoals`, `liveVisitors` with `visitorId` equal to `sessionId` and without `entryPath`, `returning`, `utmCampaign`, `affiliateSlug`, `conversionCount`, or `funnel`, and `FEDERATION_PUBLIC_FORBIDDEN` for sessions, journeys, conversions, goals, funnels, affiliates, vitals, the site map, and the configure scope.
 - Session and visitor journeys include bounded custom properties. Hosts must never place personal data or secrets in event properties.
 - Audit retained routes, identity strategy, sessions, live location, campaigns, affiliates, conversions, custom properties, retention, and intended organization membership before granting federation; stop if their sensitivity or audience cannot be established.
-- Overview ranges require complete UTC hour or day buckets. Manual pagination honors `numItems` and `cursor` only.
+- Overview ranges require complete UTC hours, complete UTC days, or (hosts from `alpha.11`, optional capability `localDays`) complete calendar days in the timezone every requested site shares; `metadata.range.timezone` names the zone the answer follows. Manual pagination honors `numItems` and `cursor` only.
+- Right after an accepted request, `liveVisitors` and `sessionJourney` reflect it; `listSessions` and the bucketed reports can trail it by seconds, so an empty result from those is not proof of failed ingestion.
 - `dataCoverage` echoes the authorized site ID but returns no event, visitor, or session IDs.
 - `vitalsReport` returns p75, averages, and exact good/needs-improvement/poor counts per metric, page, and device — never individual measurements.
-- `siteMap` returns per-route totals (pageviews, estimated visitors, entries, derived exits and bounces, time on page) and route-to-route transition counts, with numeric, UUID, and long hexadecimal segments collapsed to `:id` — never sessions, visitor IDs, or query strings. `liveVisitors` adds `previousPath` and `movedAt` when a visitor moves between routes.
+- `siteMap` returns per-route totals (pageviews, estimated visitors, entries, derived exits and bounces, time on page) and route-to-route transition counts, with numeric, UUID, and long hexadecimal segments collapsed to `:id` — never sessions, visitor IDs, or query strings. `liveVisitors` adds `previousPath` and `movedAt` when a visitor moves between routes, and since 0.1.0 the intent facts of the session — `entryPath`, `returning`, `utmCampaign`, `affiliateSlug`, `conversionCount`, and the furthest `funnel` step — which `visitorHeat` from the package turns into the dashboard's hot/warm/cold score.

package/package.json

@@ -6,7 +6,7 @@
   "bugs": {
     "url": "https://github.com/amageweb/amage-rastro/issues"
   },
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
@@ -58,6 +58,7 @@
     "src/test.ts",
     "src/component/**/*.ts",
     "!src/component/**/*.test.ts",
+    "src/tracker/generated.ts",
     "scripts/benchmark-ingest.mjs",
     "scripts/generate-federation-keys.mjs",
     "agent/manifest.json",

package/src/component/_generated/api.ts

@@ -23,8 +23,11 @@ import type * as http from "../http.js";
 import type * as identity from "../identity.js";
 import type * as ingest from "../ingest.js";
 import type * as live from "../live.js";
+import type * as localTime from "../localTime.js";
 import type * as reports from "../reports.js";
 import type * as retention from "../retention.js";
+import type * as rollupStore from "../rollupStore.js";
+import type * as rollups from "../rollups.js";
 import type * as sanitize from "../sanitize.js";
 import type * as sites from "../sites.js";
 import type * as useragent from "../useragent.js";
@@ -55,8 +58,11 @@ const fullApi: ApiFromModules<{
   identity: typeof identity;
   ingest: typeof ingest;
   live: typeof live;
+  localTime: typeof localTime;
   reports: typeof reports;
   retention: typeof retention;
+  rollupStore: typeof rollupStore;
+  rollups: typeof rollups;
   sanitize: typeof sanitize;
   sites: typeof sites;
   useragent: typeof useragent;

package/src/component/_generated/component.ts

@@ -273,7 +273,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             range: {
               boundary: "inclusive";
               from: number;
-              timezone: "UTC";
+              timezone: string;
               to: number;
             };
             uniqueVisitors: {
@@ -301,6 +301,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             dataset:
               | "overviewHour"
               | "overviewDay"
+              | "overviewLocalDay"
               | "events"
               | "sessions"
               | "conversions"
@@ -339,7 +340,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             range: {
               boundary: "inclusive";
               from: number;
-              timezone: "UTC";
+              timezone: string;
               to: number;
             };
           };
@@ -392,7 +393,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             range: {
               boundary: "inclusive";
               from: number;
-              timezone: "UTC";
+              timezone: string;
               to: number;
             };
           };
@@ -482,6 +483,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             lastSeenAt: number;
             latitude?: number;
             longitude?: number;
+            newVisitor?: boolean;
             os: string;
             pageviewCount: number;
             referrer?: string;
@@ -508,12 +510,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Array<{
           _creationTime: number;
           _id: string;
+          affiliateSlug?: string;
           browser: string;
           city?: string;
+          conversionCount?: number;
           country?: string;
           device: string;
+          entryPath?: string;
           eventCount: number;
           expiresAt: number;
+          funnel?: { funnelId: string; step: number; steps: number };
           lastSeenAt: number;
           latitude?: number;
           longitude?: number;
@@ -522,10 +528,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           pageviewCount: number;
           path: string;
           previousPath?: string;
+          returning?: boolean;
           sessionId: string;
           siteId: string;
           source: string;
           startedAt: number;
+          utmCampaign?: string;
           visitorId: string;
         }>,
         Name
@@ -545,14 +553,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           interval: "hour" | "day";
           metadata: {
             breakdowns: {
-              topBrowsers: "eventVolume";
-              topCampaigns: "eventVolume";
-              topCountries: "eventVolume";
-              topDevices: "eventVolume";
+              topBrowsers: "pageviews" | "sessions" | "eventVolume";
+              topCampaigns: "pageviews" | "sessions" | "eventVolume";
+              topCountries: "pageviews" | "sessions" | "eventVolume";
+              topDevices: "pageviews" | "sessions" | "eventVolume";
               topEvents: "eventVolume";
               topGoals: "goalCompletionVolume";
-              topPages: "eventVolume";
-              topSources: "eventVolume";
+              topMediums: "pageviews" | "sessions" | "eventVolume";
+              topOutbound: "eventVolume";
+              topPages: "pageviews" | "sessions" | "eventVolume";
+              topSources: "pageviews" | "sessions" | "eventVolume";
             };
             coverage: {
               availableFrom: number | null;
@@ -561,6 +571,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               retainedBefore: number | null;
               state: "complete" | "partial" | "retained" | "unavailable";
             };
+            dimensionsSince: number | null;
+            engagement: "counted" | "unavailable";
             features: {
               botDetection: "userAgent";
               errorInsights: "unsupported";
@@ -570,7 +582,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             range: {
               boundary: "inclusive";
               from: number;
-              timezone: "UTC";
+              timezone: string;
               to: number;
             };
             visitors: {
@@ -583,9 +595,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           };
           timeSeries: Array<{
             clicks: number;
+            continuedSessions: number;
             conversions: number;
             customEvents: number;
+            durationMs: number;
             events: number;
+            newVisitors: number;
             outboundClicks: number;
             pageviews: number;
             revenueCents: number;
@@ -624,6 +639,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topMediums: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
+          topOutbound: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topPages: Array<{
             count: number;
             revenueCents: number;
@@ -636,9 +661,12 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           }>;
           totals: {
             clicks: number;
+            continuedSessions: number;
             conversions: number;
             customEvents: number;
+            durationMs: number;
             events: number;
+            newVisitors: number;
             outboundClicks: number;
             pageviews: number;
             revenueCents: number;
@@ -731,7 +759,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             range: {
               boundary: "inclusive";
               from: number;
-              timezone: "UTC";
+              timezone: string;
               to: number;
             };
             visitors: { basis: "estimatedUnique"; exact: boolean };
@@ -820,7 +848,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             range: {
               boundary: "inclusive";
               from: number;
-              timezone: "UTC";
+              timezone: string;
               to: number;
             };
           };
@@ -1040,6 +1068,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         }>,
         Name
       >;
+      localDays: FunctionReference<
+        "query",
+        "internal",
+        { siteId: string },
+        { since: number; timezone: string } | null,
+        Name
+      >;
       update: FunctionReference<
         "mutation",
         "internal",

package/src/component/constants.ts

@@ -38,6 +38,12 @@ export const FEATURE_REPORT_DOCUMENT_RESERVE = 500;
 export const REPORT_ROLLUP_SHARDS = 2;
 export const ROLLUP_SAFETY_DELAY_MS = 5 * 60_000;
 export const RETENTION_LEASE_MS = 60_000;
+// Report rollups are folded by one leased job per site (see rollupStore.ts).
+// A run takes at most this many queued batches, stops early once the merged
+// deltas would touch this many rows, and holds its lease for this long.
+export const ROLLUP_FOLD_BATCH_DOCS = 200;
+export const ROLLUP_FOLD_MAX_ROWS = 1_500;
+export const ROLLUP_FOLD_LEASE_MS = 60_000;
 // Shared Web Vitals histogram edges. Every Google rating threshold (LCP
 // 2500/4000, CLS×1000 100/250, INP 200/500, FCP 1800/3000, TTFB 800/1800) is
 // an edge, so rating counts stay exact while one layout serves all metrics.

package/src/component/coverage.ts

@@ -13,24 +13,64 @@ export async function ensureAnalyticsControl(
     .withIndex("by_siteId", (range) => range.eq("siteId", siteId))
     .unique();
   if (existing) {
-    if (existing.siteMapSince !== undefined) return existing;
-    // A site that predates the site map starts its map coverage at the first
-    // ingest after the upgrade; the same safety delay applies as for rollups.
-    const siteMapSince = now + ROLLUP_SAFETY_DELAY_MS;
+    // A site that predates a feature starts that feature's coverage at the
+    // first ingest after the upgrade, with the same safety delay as rollups:
+    // the site map rows, and the alpha.11 counters (pageviews and sessions
+    // per dimension slot; duration, continued sessions and new visitors per
+    // bucket), and the 0.1.0 dimensions (utm_medium and outbound hosts).
+    const stamps: {
+      siteMapSince?: number;
+      countersSince?: number;
+      localDaySince?: number;
+      dimensionsSince?: number;
+    } = {};
+    if (existing.siteMapSince === undefined) {
+      stamps.siteMapSince = now + ROLLUP_SAFETY_DELAY_MS;
+    }
+    if (existing.countersSince === undefined) {
+      stamps.countersSince = now + ROLLUP_SAFETY_DELAY_MS;
+    }
+    if (existing.localDaySince === undefined) {
+      stamps.localDaySince = now + ROLLUP_SAFETY_DELAY_MS;
+    }
+    if (existing.dimensionsSince === undefined) {
+      stamps.dimensionsSince = now + ROLLUP_SAFETY_DELAY_MS;
+    }
+    if (Object.keys(stamps).length === 0) return existing;
     await ctx.db.patch("analyticsCoverage", existing._id, {
-      siteMapSince,
+      ...stamps,
       updatedAt: now,
     });
-    return { ...existing, siteMapSince, updatedAt: now };
+    return { ...existing, ...stamps, updatedAt: now };
   }
   const fields = {
     siteId,
     generation: 1 as const,
     rollupCompleteFrom: now + ROLLUP_SAFETY_DELAY_MS,
     siteMapSince: now + ROLLUP_SAFETY_DELAY_MS,
+    countersSince: now + ROLLUP_SAFETY_DELAY_MS,
+    localDaySince: now + ROLLUP_SAFETY_DELAY_MS,
+    dimensionsSince: now + ROLLUP_SAFETY_DELAY_MS,
     retained,
     updatedAt: now,
   };
   const _id = await ctx.db.insert("analyticsCoverage", fields);
   return { ...fields, _id, _creationTime: now };
 }
+
+/**
+ * A site's local-day buckets are computed in its timezone at ingest, so a
+ * changed timezone restarts their coverage: rows before the change belong to
+ * the old zone's days and must not answer for the new one.
+ */
+export async function resetLocalDayCoverage(
+  ctx: MutationCtx,
+  siteId: Id<"sites">,
+  now: number,
+) {
+  const control = await ensureAnalyticsControl(ctx, siteId, now);
+  await ctx.db.patch("analyticsCoverage", control._id, {
+    localDaySince: now + ROLLUP_SAFETY_DELAY_MS,
+    updatedAt: now,
+  });
+}