@iann29/rastro 0.4.0 → 0.5.0

package/llms.txt

@@ -16,6 +16,8 @@ Do not infer federation availability from this website, a dist-tag, or a source
 ## Architecture
 
 - Tracker and telemetry: browser -> customer HTTP-actions URL -> customer Rastro component.
+- The tracker is 2,594 bytes raw and 1,395 gzip. It sends the click-ID key **names** of the landing URL in `clid` (`gclid`, `fbclid`, `ttclid`…), at most eight, never a value, and the referrer as scheme and host, so an `android-app://<package>` referrer keeps its package.
+- Tracked links (0.5.0+): browser -> customer HTTP-actions URL `/rastro/l/<slug>` -> `302` (`Cache-Control: no-store`) to a destination on one of the site's domains, with `utm_source` (platform), `utm_medium` (channel), `utm_campaign` (campaign, or the slug) and `utm_content` (slug) appended; the destination's own query and `utm_*` keys stay. Unknown or disabled slug: `404`. Clicks count in four-shard daily counters; self-declared bots are redirected and counted apart.
 - Optional field Web Vitals (alpha.6+): a second browser module at `/rastro/vitals.js` reports LCP, CLS, INP, FCP, and TTFB to the same events endpoint, into bounded daily histograms; it needs the base tracker on the page.
 - Reactive dashboard reads: amagerastro.com browser -> customer functions URL -> `rastroFederation:*`.
 - Control plane: account, organization, connection metadata, short-lived token issuance, and revocation.
@@ -30,7 +32,8 @@ 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, 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`.
+- A host on 0.5.0 re-exports `listTrackedLinks`, `createTrackedLink`, `updateTrackedLink` and `deleteTrackedLink` from that module and reverifies, which advertises the optional `trackedLinks` capability; listing needs a reader, the other three need `analytics:configure`. A host that skips it keeps working without the capability.
+- Expose only the manifest, connection status, site summaries, reports, journeys, conversions, affiliates, funnels, goals, web vitals, coverage, tracked links, 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.
@@ -55,6 +58,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 - Vitals report maximum: 90 complete UTC days; `vitals` is an optional capability that hosts before `alpha.6` do not advertise.
 - Site map maximum: 90 complete UTC days, read newest day first within 8,000 route rows; older days it could not read are declared as partial coverage. `siteMap` is an optional capability that hosts before `alpha.8` do not advertise, and its data starts at the first ingest after that upgrade.
 - Maximum live visitors: 500.
+- Tracked links: at most 200 per site; slugs are 3–32 lowercase letters, digits or hyphens, unique across the deployment; `listTrackedLinks` reports clicks and bots all time and over the 30 UTC days ending on the `now` it is given. `trackedLinks` is an optional capability that hosts before 0.5.0, and hosts that did not re-export the four functions, do not advertise.
 - Live window: the tracker sends a `leave` when the tab hides or the page unloads, retiring the visitor about ten seconds later; a shown tab or a bfcache return sends a heartbeat at once and 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. 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.
@@ -62,6 +66,7 @@ Do not infer federation availability from this website, a dist-tag, or a source
 ## Read semantics
 
 - Times are inclusive Unix epoch milliseconds in UTC.
+- Origin (0.5.0+): a session is classified once, on its first touch, into `platform` (about forty ids), `channel` (twelve, `direct` to `ai` plus `offline`) and `evidence`, the rule that decided it. Decision order, first match wins: declared `utm_source`, click-ID name, referrer host by whole label, in-app browser, affiliate `ref`; nothing at all is the only way to be `direct`. `overview.topPlatforms`, `topChannels` and `topEvidence` rank them beside `topSources`; a `topPlatforms` value is the bare platform id for its default channel and `platform@channel` otherwise. `dataCoverage`'s `origin` dataset says from when a site carries origins; older sessions are classified on read, marked `evidence: "legacy"`, and never enter the aggregates. `source` is unchanged.
 - 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.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@iann29/rastro",
-  "description": "Privacy-first, real-time web analytics for Convex: live visitor atlas, journeys, revenue, goals, funnels, affiliates, and a 1.1 KB tracker.",
+  "description": "Privacy-first, real-time web analytics for Convex: live visitor atlas, journeys, revenue, goals, funnels, affiliates, and a 1.4 KB tracker.",
   "repository": "github:amageweb/amage-rastro",
   "homepage": "https://github.com/amageweb/amage-rastro#readme",
   "bugs": {
     "url": "https://github.com/amageweb/amage-rastro/issues"
   },
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/src/component/_generated/api.ts

@@ -24,12 +24,15 @@ 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 origin from "../origin.js";
+import type * as platforms from "../platforms.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 trackedLinks from "../trackedLinks.js";
 import type * as useragent from "../useragent.js";
 import type * as validators from "../validators.js";
 import type * as visitors from "../visitors.js";
@@ -59,12 +62,15 @@ const fullApi: ApiFromModules<{
   ingest: typeof ingest;
   live: typeof live;
   localTime: typeof localTime;
+  origin: typeof origin;
+  platforms: typeof platforms;
   reports: typeof reports;
   retention: typeof retention;
   rollupStore: typeof rollupStore;
   rollups: typeof rollups;
   sanitize: typeof sanitize;
   sites: typeof sites;
+  trackedLinks: typeof trackedLinks;
   useragent: typeof useragent;
   validators: typeof validators;
   visitors: typeof visitors;

package/src/component/_generated/component.ts

@@ -183,6 +183,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             city?: string;
             country?: string;
             device?: string;
+            inApp?: string;
             latitude?: number;
             longitude?: number;
             os?: string;
@@ -190,6 +191,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           };
           events: Array<{
             affiliateSlug?: string;
+            clid?: Array<string>;
             currency?: string;
             eventId: string;
             href?: string;
@@ -310,7 +312,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               | "funnels"
               | "affiliates"
               | "vitals"
-              | "siteMap";
+              | "siteMap"
+              | "origin";
           }>;
           from: number;
           siteId: string;
@@ -375,6 +378,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           affiliateId?: string;
           affiliateSlug?: string;
           browser: string;
+          channel?:
+            | "direct"
+            | "organic_search"
+            | "paid_search"
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "ai"
+            | "display"
+            | "referral"
+            | "offline";
           city?: string;
           conversionCount: number;
           country?: string;
@@ -383,6 +399,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           durationMs: number;
           entryPath: string;
           eventCount: number;
+          evidence?:
+            | "utm"
+            | "clickId"
+            | "referrer"
+            | "inApp"
+            | "affiliate"
+            | "none"
+            | "legacy";
           exitPath: string;
           lastSeenAt: number;
           latitude?: number;
@@ -390,6 +414,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           newVisitor?: boolean;
           os: string;
           pageviewCount: number;
+          platform?: string;
           referrer?: string;
           revenueCents: number;
           sessionId: string;
@@ -513,6 +538,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             affiliateId?: string;
             affiliateSlug?: string;
             browser: string;
+            channel?:
+              | "direct"
+              | "organic_search"
+              | "paid_search"
+              | "organic_social"
+              | "paid_social"
+              | "messaging"
+              | "email"
+              | "affiliate"
+              | "ai"
+              | "display"
+              | "referral"
+              | "offline";
             city?: string;
             conversionCount: number;
             country?: string;
@@ -521,6 +559,14 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             durationMs: number;
             entryPath: string;
             eventCount: number;
+            evidence?:
+              | "utm"
+              | "clickId"
+              | "referrer"
+              | "inApp"
+              | "affiliate"
+              | "none"
+              | "legacy";
             exitPath: string;
             lastSeenAt: number;
             latitude?: number;
@@ -528,6 +574,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             newVisitor?: boolean;
             os: string;
             pageviewCount: number;
+            platform?: string;
             referrer?: string;
             revenueCents: number;
             sessionId: string;
@@ -597,13 +644,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             breakdowns: {
               topBrowsers: "pageviews" | "sessions" | "eventVolume";
               topCampaigns: "pageviews" | "sessions" | "eventVolume";
+              topChannels: "pageviews" | "sessions" | "eventVolume";
               topCountries: "pageviews" | "sessions" | "eventVolume";
               topDevices: "pageviews" | "sessions" | "eventVolume";
               topEvents: "eventVolume";
+              topEvidence: "pageviews" | "sessions" | "eventVolume";
               topGoals: "goalCompletionVolume";
               topMediums: "pageviews" | "sessions" | "eventVolume";
               topOutbound: "eventVolume";
               topPages: "pageviews" | "sessions" | "eventVolume";
+              topPlatforms: "pageviews" | "sessions" | "eventVolume";
               topSources: "pageviews" | "sessions" | "eventVolume";
             };
             coverage: {
@@ -661,6 +711,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topChannels: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topCountries: Array<{
             count: number;
             revenueCents: number;
@@ -676,6 +731,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topEvidence: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topGoals: Array<{
             count: number;
             revenueCents: number;
@@ -696,6 +756,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             revenueCents: number;
             value: string;
           }>;
+          topPlatforms: Array<{
+            count: number;
+            revenueCents: number;
+            value: string;
+          }>;
           topSources: Array<{
             count: number;
             revenueCents: number;
@@ -1140,6 +1205,92 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         Name
       >;
     };
+    trackedLinks: {
+      create: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          campaign?: string;
+          channel:
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "display"
+            | "referral"
+            | "offline";
+          createdBy: string;
+          destination: string;
+          platform: string;
+          siteId: string;
+          slug: string;
+        },
+        string,
+        Name
+      >;
+      list: FunctionReference<
+        "query",
+        "internal",
+        { now: number; siteId: string },
+        Array<{
+          _creationTime: number;
+          _id: string;
+          bots: number;
+          botsLast30Days: number;
+          campaign?: string;
+          channel:
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "display"
+            | "referral"
+            | "offline";
+          clicks: number;
+          clicksLast30Days: number;
+          createdAt: number;
+          createdBy: string;
+          destination: string;
+          disabledAt?: number;
+          platform: string;
+          siteId: string;
+          slug: string;
+        }>,
+        Name
+      >;
+      remove: FunctionReference<
+        "mutation",
+        "internal",
+        { linkId: string; siteId: string },
+        null,
+        Name
+      >;
+      update: FunctionReference<
+        "mutation",
+        "internal",
+        {
+          campaign?: string | null;
+          channel?:
+            | "organic_social"
+            | "paid_social"
+            | "messaging"
+            | "email"
+            | "affiliate"
+            | "display"
+            | "referral"
+            | "offline";
+          destination?: string;
+          disabled?: boolean;
+          linkId: string;
+          platform?: string;
+          siteId: string;
+        },
+        null,
+        Name
+      >;
+    };
     visitors: {
       link: FunctionReference<
         "mutation",

package/src/component/constants.ts

@@ -31,6 +31,13 @@ export const MAX_SITES_PER_OWNER = 100;
 export const MAX_GOALS_PER_SITE = 50;
 export const MAX_FUNNELS_PER_SITE = 20;
 export const MAX_AFFILIATES_PER_SITE = 100;
+export const MAX_TRACKED_LINKS_PER_SITE = 200;
+// A tracked link's clicks spread over this many counter rows, so a link that
+// goes viral writes at four times one document's rate. Four and not more
+// because every shard is read back: the list reads a link's all-time shards
+// plus its last 30 days, and a full site of 200 links must stay under the
+// 32,000 documents a query may read (see trackedLinks.ts).
+export const TRACKED_LINK_CLICK_SHARDS = 4;
 export const MAX_FUNNEL_STEPS = 10;
 export const MAX_PROPERTIES = 16;
 export const MAX_REPORT_SITES = 10;

package/src/component/coverage.ts

@@ -17,12 +17,14 @@ export async function ensureAnalyticsControl(
     // 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).
+    // bucket), the 0.1.0 dimensions (utm_medium and outbound hosts), and
+    // the session origins (platform, channel and evidence).
     const stamps: {
       siteMapSince?: number;
       countersSince?: number;
       localDaySince?: number;
       dimensionsSince?: number;
+      originSince?: number;
     } = {};
     if (existing.siteMapSince === undefined) {
       stamps.siteMapSince = now + ROLLUP_SAFETY_DELAY_MS;
@@ -36,6 +38,9 @@ export async function ensureAnalyticsControl(
     if (existing.dimensionsSince === undefined) {
       stamps.dimensionsSince = now + ROLLUP_SAFETY_DELAY_MS;
     }
+    if (existing.originSince === undefined) {
+      stamps.originSince = now + ROLLUP_SAFETY_DELAY_MS;
+    }
     if (Object.keys(stamps).length === 0) return existing;
     await ctx.db.patch("analyticsCoverage", existing._id, {
       ...stamps,
@@ -51,6 +56,7 @@ export async function ensureAnalyticsControl(
     countersSince: now + ROLLUP_SAFETY_DELAY_MS,
     localDaySince: now + ROLLUP_SAFETY_DELAY_MS,
     dimensionsSince: now + ROLLUP_SAFETY_DELAY_MS,
+    originSince: now + ROLLUP_SAFETY_DELAY_MS,
     retained,
     updatedAt: now,
   };

package/src/component/http.ts

@@ -21,7 +21,9 @@ import {
 import { isPlainRecord } from "./guards.js";
 import { alignClock, sanitizeEvent } from "./sanitize.js";
 import { deriveClientKey, deriveVisitorKey, randomSecret } from "./identity.js";
-import { classifyClient, isKnownBot } from "./useragent.js";
+import { isTrackedLinkSlug, trackedLinkLocation } from "./trackedLinks.js";
+import { classifyClient, inAppPlatform, isKnownBot } from "./useragent.js";
+import { knownClickIds } from "./origin.js";
 import type { TrackerEvent } from "./validators.js";
 import {
   RASTRO_VERSION,
@@ -174,9 +176,11 @@ http.route({
             userAgent,
           })
         : undefined;
+    const inApp = inAppPlatform(userAgent);
     const context = {
       ...edgeGeo,
       ...classifyClient(userAgent, request.headers),
+      ...(inApp ? { inApp } : {}),
       ...(visitorKey ? { visitorKey } : {}),
     };
     // Origin is a browser control: any other sender writes the header it
@@ -304,6 +308,46 @@ http.route({
   ),
 });
 
+// A tracked link. The click is counted — as a bot when the agent says it is
+// one, so link unfurlers never inflate the clicks but still get the page — and
+// the visitor goes on with the link's utm_* appended. Unknown and disabled
+// slugs answer 404.
+http.route({
+  pathPrefix: "/l/",
+  method: "GET",
+  handler: httpAction(async (ctx, request) => {
+    const slug = (
+      new URL(request.url).pathname.split("/").filter(Boolean).pop() ?? ""
+    ).toLowerCase();
+    const link = isTrackedLinkSlug(slug)
+      ? await ctx.runMutation(internal.trackedLinks.recordClick, {
+          slug,
+          bot: isKnownBot(
+            (await readRequestMetadata(ctx)).userAgent ??
+              request.headers.get("user-agent") ??
+              "",
+          ),
+        })
+      : null;
+    if (!link) {
+      return new Response("Not found", {
+        status: 404,
+        headers: {
+          "Content-Type": "text/plain; charset=utf-8",
+          "Cache-Control": "no-store",
+        },
+      });
+    }
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: trackedLinkLocation(link),
+        "Cache-Control": "no-store",
+      },
+    });
+  }),
+});
+
 http.route({
   path: "/health",
   method: "GET",
@@ -434,6 +478,7 @@ function parseEvent(value: unknown): TrackerEvent {
     throw new Error("event is missing required fields");
   }
   const properties = parseProperties(value.properties);
+  const clid = parseClickIds(value.clid);
   return {
     eventId: value.eventId,
     sessionId: value.sessionId,
@@ -467,9 +512,19 @@ function parseEvent(value: unknown): TrackerEvent {
     ...(optionalNumber(value.value, "value") !== undefined
       ? { value: optionalNumber(value.value, "value") }
       : {}),
+    ...(clid ? { clid } : {}),
   };
 }
 
+/** Click-ID key names: unknown keys are dropped, never a reason to reject. */
+function parseClickIds(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((key) => typeof key !== "string")) {
+    throw new Error("clid must be an array of strings");
+  }
+  return knownClickIds(value as string[]);
+}
+
 function parseProperties(value: unknown): TrackerEvent["properties"] {
   if (value === undefined) return undefined;
   if (!isPlainRecord(value)) throw new Error("properties must be an object");

package/src/component/ingest.ts

@@ -54,6 +54,7 @@ import {
 } from "./eventStore.js";
 import {
   cleanString,
+  externalReferrer,
   isValidMoney,
   measureBatchBytes,
   normalizeRoute,
@@ -74,6 +75,8 @@ import {
   ingestResultValidator,
   trackerEventValidator,
   trustedConversionValidator,
+  type Channel,
+  type Evidence,
   type IngestContext,
   type TrackerEvent,
 } from "./validators.js";
@@ -85,6 +88,7 @@ import {
   type RouteRollupDelta,
 } from "./rollupStore.js";
 import { localDayStart, localDayTimezone } from "./localTime.js";
+import { classifyOrigin, platformDimensionValue } from "./origin.js";
 
 type DimensionType =
   | "source"
@@ -96,7 +100,10 @@ type DimensionType =
   | "event"
   | "goal"
   | "medium"
-  | "outbound";
+  | "outbound"
+  | "platform"
+  | "channel"
+  | "evidence";
 
 type Dimension = { type: DimensionType; value: string };
 type DimensionDelta = Dimension & {
@@ -145,6 +152,10 @@ type SessionState = {
   continued: boolean;
   startedAt: number;
   source: string;
+  /** The first touch's origin; absent on sessions recorded before it. */
+  platform?: string;
+  channel?: Channel;
+  evidence?: Evidence;
   visitorKey: string;
   utmCampaign?: string;
   utmMedium?: string;
@@ -567,6 +578,7 @@ export const ingestBatch = mutation({
         reportRollupDeltas,
         recordTelemetry: true,
         timezone,
+        siteDomains: site.domains,
         financialConversion: false,
         trustedGoalKey: undefined,
         now,
@@ -697,6 +709,7 @@ export const trackConversion = mutation({
       reportRollupDeltas,
       recordTelemetry: existingTelemetry === null && !telemetry.saturated,
       timezone: localDayTimezone(site.timezone),
+      siteDomains: site.domains,
       financialConversion: true,
       trustedGoalKey,
       now: Date.now(),
@@ -835,6 +848,8 @@ async function accountEvent(
     recordTelemetry: boolean;
     /** The site's timezone when it keeps local-day buckets. */
     timezone?: string;
+    /** The site's own domains: a referrer on them is not an origin. */
+    siteDomains: string[];
     financialConversion: boolean;
     trustedGoalKey: string | undefined;
     now: number;
@@ -848,6 +863,7 @@ async function accountEvent(
         input.siteId,
         event,
         input.context,
+        input.siteDomains,
         input.existingSession,
         input.financialConversion,
         input.reportRollupDeltas,
@@ -969,6 +985,23 @@ async function accountEvent(
     event.type === "outbound" ? publicUrlHost(event.href) : undefined;
   const dimensions: Dimension[] = [
     { type: "source", value: session.source },
+    // A session recorded before origins carries none, and fills no slot.
+    ...(session.platform && session.channel && session.evidence
+      ? ([
+          {
+            type: "platform",
+            // The value carries the channel too when it is not the
+            // platform's default, so the pair survives without its own
+            // dimension (splitPlatformDimension reads it back).
+            value: platformDimensionValue({
+              platform: session.platform,
+              channel: session.channel,
+            }),
+          },
+          { type: "channel", value: session.channel },
+          { type: "evidence", value: session.evidence },
+        ] satisfies Dimension[])
+      : []),
     ...campaignDimensions,
     ...(outboundHost
       ? [{ type: "outbound", value: outboundHost } satisfies Dimension]
@@ -1035,6 +1068,9 @@ async function accountTrustedSession(
     continued: false,
     startedAt: existing.startedAt,
     source: existing.source,
+    platform: existing.platform,
+    channel: existing.channel,
+    evidence: existing.evidence,
     utmCampaign: existing.utmCampaign,
     utmMedium: existing.utmMedium,
     entryPath: existing.entryPath,
@@ -1059,6 +1095,7 @@ async function upsertSession(
   siteId: Id<"sites">,
   event: TrackerEvent,
   context: IngestContext,
+  siteDomains: string[],
   existing: CachedDocument<"sessions"> | null,
   financialConversion: boolean,
   reportRollupDeltas: ReportRollupDeltas,
@@ -1156,6 +1193,9 @@ async function upsertSession(
       continued: event.type === "pageview" && existing.pageviewCount === 1,
       startedAt,
       source: existing.source,
+      platform: existing.platform,
+      channel: existing.channel,
+      evidence: existing.evidence,
       utmCampaign: existing.utmCampaign,
       utmMedium: existing.utmMedium,
       entryPath: existing.entryPath,
@@ -1206,6 +1246,17 @@ async function upsertSession(
       .first();
     if (alias) isNewVisitor = false;
   }
+  // First touch only, like `source`: the session keeps where it came from.
+  // An affiliate channel needs this landing's own `ref` to have resolved; a
+  // visitor's standing attribution alone is not how this visit arrived.
+  const origin = classifyOrigin({
+    utmSource,
+    utmMedium,
+    clickIds: event.clid,
+    referrer: externalReferrer(event.referrer, siteDomains),
+    inApp: context.inApp,
+    affiliate: event.affiliateSlug !== undefined && attribution !== undefined,
+  });
   const fields: Omit<Doc<"sessions">, "_id" | "_creationTime"> = {
     siteId,
     sessionId: event.sessionId,
@@ -1218,6 +1269,7 @@ async function upsertSession(
     newVisitor: isNewVisitor,
     ...(event.referrer ? { referrer: event.referrer } : {}),
     source,
+    ...origin,
     ...(utmSource ? { utmSource } : {}),
     ...(utmMedium ? { utmMedium } : {}),
     ...(utmCampaign ? { utmCampaign } : {}),
@@ -1274,6 +1326,7 @@ async function upsertSession(
     continued: false,
     startedAt: event.timestamp,
     source,
+    ...origin,
     utmCampaign,
     utmMedium,
     entryPath: event.path,