@tokenoftrust/storefront-runner 4.9.3 → 4.10.0

package/packages/public-runtime/src/integration/render-phases.ts

@@ -108,7 +108,7 @@ export interface IntegrationBootDescriptor {
   siteSurface: EffectivePlan["environment"]["siteSurface"];
   tenantPublicId: string;
   /**
-   * The tenant's EU/UK visitor policy when it is not the `count-only` default. The
+   * The tenant's EU/UK visitor policy when it is not the `ask` default. The
    * early consent boot reads it together with the edge's region class.
    */
   euUkVisitors?: EffectivePlan["euUkVisitors"];
@@ -182,7 +182,6 @@ export function renderIntegrationPhases(
   const bodyDeferred =
     phaseBoundary("document.deferred") +
     `<div data-tot-integration-deferred hidden></div>` +
-    viewerAnalyticsChoicesLink(plan) +
     lifecycleHostScript();
 
   return { head, bodyStart, bodyDeferred };
@@ -240,17 +239,23 @@ function inlineScript(source: string, nonce: string): string {
 
 /** Renderer-owned, provider-neutral viewer control: identical in both document mounts. */
 function viewerAnalyticsConsentStyle(nonce: string): string {
-  const style = `.tot-analytics-consent{position:fixed;z-index:900;right:1rem;bottom:1rem;display:flex;max-width:min(30rem,calc(100vw - 2rem));align-items:center;gap:.65rem;padding:.7rem .8rem;border:1px solid var(--color-border,#cbd5e1);border-radius:.75rem;background:var(--color-bg,#fff);color:var(--color-text,#111827);box-shadow:0 8px 30px rgba(15,23,42,.18);font:500 .75rem/1.25 system-ui,sans-serif}.tot-analytics-consent__copy{display:grid;gap:.15rem;min-width:8rem}.tot-analytics-consent__detail{color:var(--color-muted,#475569);font-size:.68rem}.tot-analytics-consent__actions{display:flex;gap:.4rem}.tot-analytics-consent button{border:1px solid currentColor;border-radius:999px;background:transparent;color:inherit;padding:.4rem .65rem;font:inherit;cursor:pointer}.tot-analytics-consent button:disabled{cursor:default;opacity:.45}@media(max-width:34rem){.tot-analytics-consent{left:1rem;right:1rem;align-items:flex-start;flex-direction:column}.tot-analytics-consent__actions{width:100%}.tot-analytics-consent button{flex:1}}.tot-analytics-consent[hidden]{display:none}.tot-analytics-choices{display:flex;justify-content:center;padding:.75rem 1rem;background:var(--color-bg,#fff)}.tot-analytics-choices__toggle{border:0;background:none;padding:.25rem;color:var(--color-muted,#475569);font:500 .75rem/1.25 system-ui,sans-serif;text-decoration:underline;cursor:pointer}`;
+  const style = `.tot-analytics-consent{position:fixed;z-index:900;right:1rem;bottom:1rem;display:flex;max-width:min(30rem,calc(100vw - 2rem));align-items:center;gap:.65rem;padding:.7rem .8rem;border:1px solid var(--color-border,#cbd5e1);border-radius:.75rem;background:var(--color-bg,#fff);color:var(--color-text,#111827);box-shadow:0 8px 30px rgba(15,23,42,.18);font:500 .75rem/1.25 system-ui,sans-serif}.tot-analytics-consent__copy{display:grid;gap:.15rem;min-width:8rem}.tot-analytics-consent__detail{color:var(--color-muted,#475569);font-size:.68rem}.tot-analytics-consent__actions{display:flex;gap:.4rem}.tot-analytics-consent button{border:1px solid currentColor;border-radius:999px;background:transparent;color:inherit;padding:.4rem .65rem;font:inherit;cursor:pointer}.tot-analytics-consent button:disabled{cursor:default;opacity:.45}@media(max-width:34rem){.tot-analytics-consent{left:1rem;right:1rem;align-items:flex-start;flex-direction:column}.tot-analytics-consent__actions{width:100%}.tot-analytics-consent button{flex:1}}.tot-analytics-consent[hidden]{display:none}`;
   return `<style${nonce ? ` nonce="${nonce}"` : ""}>${style}</style>`;
 }
 
-/** The id the persistent "Analytics choices" toggle names in `aria-controls`. */
+/**
+ * The id a tenant's Privacy Policy "Analytics choices" button names in `aria-controls`.
+ * The engine renders no visible route to the control: the tenant places that button in
+ * its own Privacy Policy, and the lifecycle host binds it
+ * (`bootViewerAnalyticsConsentControl`). Markup contract:
+ * `docs/architecture/analytics-activation.md`.
+ */
 const VIEWER_ANALYTICS_CONSENT_CONTROL_ID = "tot-analytics-consent";
 
 function viewerAnalyticsConsentControl(): string {
   return `<aside id="${VIEWER_ANALYTICS_CONSENT_CONTROL_ID}" class="tot-analytics-consent" data-tot-analytics-consent-control aria-label="Analytics privacy settings" hidden>` +
     `<span class="tot-analytics-consent__copy"><strong data-tot-analytics-consent-status aria-live="polite">Analytics off</strong>` +
-    `<span class="tot-analytics-consent__detail">Choose whether analytics may run on this site.</span></span>` +
+    `<span class="tot-analytics-consent__detail" data-tot-analytics-consent-detail>Choose whether analytics may run on this site.</span></span>` +
     `<span class="tot-analytics-consent__actions">` +
     `<button type="button" data-tot-analytics-consent-decision="granted" aria-pressed="false" disabled>Allow</button>` +
     `<button type="button" data-tot-analytics-consent-decision="denied" aria-pressed="true" disabled>Decline</button>` +
@@ -258,19 +263,6 @@ function viewerAnalyticsConsentControl(): string {
     `</span></aside>`;
 }
 
-/**
- * The persistent, platform-owned way to reach the control: a disclosure button placed
- * after the tenant's own footer, on every page whose plan asks for analytics consent.
- * The lifecycle host binds it (`bootViewerAnalyticsConsentControl`); no inline handler.
- */
-function viewerAnalyticsChoicesLink(plan: EffectivePlan): string {
-  if (!plan.consentNeeds.includes("analytics")) return "";
-  return `<div class="tot-analytics-choices">` +
-    `<button type="button" class="tot-analytics-choices__toggle" data-tot-analytics-choices-toggle ` +
-    `aria-controls="${VIEWER_ANALYTICS_CONSENT_CONTROL_ID}" aria-expanded="false">Analytics choices</button>` +
-    `</div>`;
-}
-
 /**
  * Replace every {@link INTEGRATION_NONCE_PLACEHOLDER} in `text` (an HTML body or a
  * CSP header value) with one fresh per-response `nonce`. Idempotent on text with no

package/packages/public-runtime/src/integration/resolve.ts

@@ -68,7 +68,7 @@ export interface ResolvePlanInput {
   tenantPublicId: string;
   environment: BrowserEnvironment;
   declarations: readonly IntegrationDeclarationInput[];
-  /** The tenant's EU/UK visitor policy; absent means `count-only`. */
+  /** The tenant's EU/UK visitor policy; absent means `ask`. */
   euUkVisitors?: EuUkVisitorPolicy;
 }
 
@@ -98,7 +98,7 @@ export function resolveEffectivePlan(
   }
 
   if (input.euUkVisitors !== undefined && !isEuUkVisitorPolicy(input.euUkVisitors)) {
-    v.add("euUkVisitors", "unknown_enum", 'euUkVisitors must be "count-only", "full", or "none".');
+    v.add("euUkVisitors", "unknown_enum", 'euUkVisitors must be "ask", "count-only", "full", or "none".');
   }
 
   if (!Array.isArray(input.declarations)) {
@@ -218,7 +218,7 @@ export function resolveEffectivePlan(
     schemaVersion: EFFECTIVE_PLAN_SCHEMA_VERSION,
     environment: envResult.ok ? envResult.value : input.environment,
     tenantPublicId: input.tenantPublicId,
-    ...(input.euUkVisitors === "full" || input.euUkVisitors === "none"
+    ...(isEuUkVisitorPolicy(input.euUkVisitors) && input.euUkVisitors !== "ask"
       ? { euUkVisitors: input.euUkVisitors }
       : {}),
     integrations,

package/packages/public-runtime/src/integration/tenant-analytics.ts

@@ -0,0 +1,250 @@
+/**
+ * Tenant-owned analytics declaration surface (TIER 1).
+ *
+ * A tenant commits an `analytics.json` at the root of its own tree (`tenants/<id>/**`), and
+ * this materializes it into the already-consumed declaration seam
+ * ({@link IntegrationDeclarationInput}[], merged into the render plan by the interim bridge).
+ * It adds no runtime: it is a third producer into an existing consumer, alongside the
+ * platform-authored `tenant.integrations` and the D1-backed managed installs.
+ *
+ * Each declared destination is built by the reviewed {@link buildPlatformAdapterDeclaration},
+ * which fail-closes on an unknown adapter, a missing/invalid live id, an invalid per-stage id,
+ * or a non-live stage that reuses the live id.
+ *
+ * One core, every caller:
+ *   - PUBLISH validation — the controlplane's `analytics-declaration` validator runs this on
+ *     every candidate, reconcile, preview build and publish, and refuses the artifact on any
+ *     violation. `agency-kit/tools/lib/analytics-declaration.mjs` reports the same violations
+ *     to the plain-node surfaces (`tot validate`, validate-site, materialize-tenant); a shared
+ *     fixture set pins the two together.
+ *   - RUNTIME materialization — the storefront's `loadTenantAnalyticsDeclarations` is
+ *     fail-closed: an invalid file yields no declarations and a value-free diagnostic.
+ */
+import {
+  analyticsViolationText,
+  parseAnalyticsDeclaration,
+} from "../../../../agency-kit/tools/lib/analytics-declaration.mjs";
+import type { BrowserEnvironment } from "./environment.js";
+import { buildPlatformAdapterDeclaration } from "./platform-adapters.js";
+import { isEuUkVisitorPolicy, type EuUkVisitorPolicy } from "./plan.js";
+import type { IntegrationDeclarationInput } from "./resolve.js";
+import { Violations, isPlainObject, rejectUnknownKeys, type ContractViolation } from "./result.js";
+import { ENVIRONMENT_SCHEMA_VERSION } from "./version.js";
+
+/** The tenant-owned file that declares measurement destinations, at the tenant tree's root. */
+export const TENANT_ANALYTICS_FILE = "analytics.json";
+
+/**
+ * The current `analytics.json` contract version. Kept out of `version.ts`, which the GA4 sandbox
+ * bundles: a new export there changes that bundle's pinned CSP hash.
+ */
+export const TENANT_ANALYTICS_SCHEMA_VERSION = 1 as const;
+
+/** One declared measurement destination: a first-class adapter + its per-stage public ids. */
+export interface TenantAnalyticsDestination {
+  /** The first-class platform adapter id, e.g. `platform.google-measurement`. */
+  adapter: string;
+  /** Public per-stage destination ids. `live` is required; non-live stages take SEPARATE test ids. */
+  ids: Record<string, unknown>;
+}
+
+/** The result of materializing a tenant's `analytics.json` into declarations. */
+export interface TenantAnalyticsMaterialization {
+  /** True only when EVERY declared destination validated; false surfaces `violations`. */
+  ok: boolean;
+  /** The materialized declarations, in declared order. Empty whenever `ok` is false. */
+  declarations: readonly IntegrationDeclarationInput[];
+  /**
+   * The declared `euUkVisitors` policy when it is not the `ask` default. Absent
+   * whenever `ok` is false, so an invalid file never widens EU/UK collection.
+   */
+  euUkVisitors?: Exclude<EuUkVisitorPolicy, "ask">;
+  /** Per-field violations for the publish surface. Empty whenever `ok` is true. */
+  violations: readonly ContractViolation[];
+}
+
+/**
+ * The fixed environment the declaration is CONSTRUCTED against. A first-class adapter
+ * declaration is environment-INDEPENDENT in content — its per-stage ids are all baked
+ * into `publicConfig` and the client picks the current stage at render time — so the
+ * environment here only satisfies {@link buildPlatformAdapterDeclaration}'s validation
+ * and its plan-derived CSP requirements. The caller must supply the tenant's real
+ * canonical host so those requirements authorize the same-site adapter frame that the
+ * browser runtime will construct.
+ */
+function constructionEnvironment(canonicalHost: string): BrowserEnvironment {
+  return {
+    schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+    siteSurface: "storefront",
+    environment: "live",
+    canonicalHost,
+    revision: "tenant-analytics-declaration",
+  };
+}
+
+const EMPTY: readonly IntegrationDeclarationInput[] = Object.freeze([]);
+
+/** Re-anchor a builder violation path under the declaring `destinations[i]` element. */
+function reanchor(violation: ContractViolation, index: number): ContractViolation {
+  const base = `destinations[${index}]`;
+  const path =
+    violation.path === "(root)" || violation.path === ""
+      ? base
+      : violation.path === "adapterId"
+        ? `${base}.adapter`
+        : violation.path.startsWith("adapterId.")
+          ? `${base}.adapter${violation.path.slice("adapterId".length)}`
+          : `${base}.${violation.path}`;
+  return { path, code: violation.code, message: violation.message };
+}
+
+/** Validate the closed shape of one declared destination before it reaches the builder. */
+function readDestination(
+  raw: unknown,
+  index: number,
+  v: Violations,
+): TenantAnalyticsDestination | undefined {
+  const base = `destinations[${index}]`;
+  if (!isPlainObject(raw)) {
+    v.add(base, "type", "A destination must be an object of { adapter, ids }.");
+    return undefined;
+  }
+  rejectUnknownKeys(raw, ["adapter", "ids"], v, base);
+  const adapter = raw["adapter"];
+  if (typeof adapter !== "string" || adapter.length === 0) {
+    v.add(`${base}.adapter`, "type", "A destination adapter must be a non-empty string.");
+    return undefined;
+  }
+  if (!isPlainObject(raw["ids"])) {
+    v.add(`${base}.ids`, "type", "ids must be an object of { stage: destinationId[] }.");
+    return undefined;
+  }
+  return { adapter, ids: raw["ids"] };
+}
+
+/**
+ * Parse and materialize a tenant's `analytics.json` content into first-class adapter
+ * declarations. `raw` is the already-parsed JSON value (or `undefined`/`null` when the
+ * tenant declares none). Fail-closed and whole-file: if ANY declared destination is
+ * invalid, NO declaration is produced and the violations name every offending field —
+ * a half-valid analytics file never partially materializes.
+ */
+export function materializeTenantAnalyticsDeclarations(input: {
+  raw: unknown;
+  tenantPublicId: string;
+  canonicalHost: string;
+}): TenantAnalyticsMaterialization {
+  const { raw, tenantPublicId, canonicalHost } = input;
+  // An undeclared tenant (no file) is the zero-cost norm, not an error.
+  if (raw === undefined || raw === null) {
+    return { ok: true, declarations: EMPTY, violations: [] };
+  }
+
+  const v = new Violations();
+  if (!isPlainObject(raw)) {
+    v.add("(root)", "type", "analytics.json must be a JSON object with a `destinations` array.");
+    return { ok: false, declarations: EMPTY, violations: v.items };
+  }
+  rejectUnknownKeys(raw, ["schemaVersion", "destinations", "euUkVisitors"], v, "");
+  const euUkVisitors = raw["euUkVisitors"];
+  if ("euUkVisitors" in raw && !isEuUkVisitorPolicy(euUkVisitors)) {
+    v.add(
+      "euUkVisitors",
+      "unknown_enum",
+      'euUkVisitors must be "ask" (the default), "count-only", "full", or "none".',
+    );
+  }
+  if ("schemaVersion" in raw && raw["schemaVersion"] !== TENANT_ANALYTICS_SCHEMA_VERSION) {
+    v.add(
+      "schemaVersion",
+      "unsupported_version",
+      `schemaVersion must equal ${TENANT_ANALYTICS_SCHEMA_VERSION}.`,
+    );
+  }
+  const destinationsRaw = raw["destinations"];
+  if (!Array.isArray(destinationsRaw)) {
+    v.add("destinations", "type", "`destinations` must be an array.");
+    return { ok: false, declarations: EMPTY, violations: v.items };
+  }
+
+  const declarations: IntegrationDeclarationInput[] = [];
+  const seenAdapters = new Set<string>();
+  destinationsRaw.forEach((destinationRaw, index) => {
+    const destination = readDestination(destinationRaw, index, v);
+    if (!destination) return;
+    // The plan resolves an app at most once and refuses the whole plan on a repeat.
+    if (seenAdapters.has(destination.adapter)) {
+      v.add(`destinations[${index}].adapter`, "duplicate", "Each adapter may be declared by one destination only.");
+      return;
+    }
+    seenAdapters.add(destination.adapter);
+    const built = buildPlatformAdapterDeclaration({
+      adapterId: destination.adapter,
+      ids: destination.ids,
+      tenantPublicId,
+      environment: constructionEnvironment(canonicalHost),
+    });
+    if (!built.ok) {
+      for (const violation of built.violations) v.items.push(reanchor(violation, index));
+      return;
+    }
+    // Namespace the ref so a tenant-declared adapter can never be mistaken for — or
+    // collide with — the same adapter installed through the managed D1 path.
+    declarations.push({ ...built.declaration, ref: `tenant-analytics:${destination.adapter}` });
+  });
+
+  if (!v.ok) return { ok: false, declarations: EMPTY, violations: v.items };
+  return {
+    ok: true,
+    declarations,
+    violations: [],
+    ...(isEuUkVisitorPolicy(euUkVisitors) && euUkVisitors !== "ask" ? { euUkVisitors } : {}),
+  };
+}
+
+/** A publish-surface violation: value-free, so it is safe to log, return or render. */
+export interface TenantAnalyticsFinding {
+  path: string;
+  code: string;
+  /** `<path>: [<code>] <fixed explanation>` — never an id or any other value from the file. */
+  message: string;
+  remedy: string;
+}
+
+function finding(violation: { path: string; code: string }): TenantAnalyticsFinding {
+  const { message, remedy } = analyticsViolationText(violation);
+  return {
+    path: violation.path,
+    code: violation.code,
+    message: `${violation.path}: [${violation.code}] ${message}`,
+    remedy,
+  };
+}
+
+/**
+ * The publish-time check of one `analytics.json` file's TEXT: every violation the materializer
+ * reports, with no declaration produced. A file that is present but unparseable is a `(root)`
+ * `invalid_json` violation and a present `null` is a `(root)` `type` violation — only an absent
+ * file declares nothing. Validity does not depend on the tenant or its host, so fixed
+ * construction values are used. The builder's own messages may quote a declared id, so each
+ * violation is re-described by its path and code alone.
+ */
+export function tenantAnalyticsDeclarationFindings(text: string): TenantAnalyticsFinding[] {
+  const parsed = parseAnalyticsDeclaration(text);
+  if (!parsed.ok) return parsed.violations.map(finding);
+  if (parsed.value === null) return [finding({ path: "(root)", code: "type" })];
+  return materializeTenantAnalyticsDeclarations({
+    raw: parsed.value,
+    tenantPublicId: "analytics-declaration-check",
+    canonicalHost: "analytics-declaration-check.invalid",
+  }).violations.map(finding);
+}
+
+/**
+ * The value-free diagnostic for a materialization the runtime refused: path and code only.
+ */
+export function describeTenantAnalyticsViolations(
+  violations: readonly ContractViolation[],
+): { path: string; code: string }[] {
+  return violations.map(({ path, code }) => ({ path, code }));
+}

package/packages/public-runtime/src/integration/visitor-region.mjs

@@ -12,7 +12,7 @@
  *   `x`  — a known country outside them
  *   `u`  — the edge could not geolocate the request
  *
- * The browser treats `eu`, `u`, and an absent or unreadable cookie alike (count-only),
+ * The browser treats `eu`, `u`, and an absent or unreadable cookie alike (the EU/UK policy),
  * so a missing signal fails closed.
  *
  * `visitorRegionClass` is closure-free: the CloudFront generator serializes it with

package/packages/public-runtime/src/tenant.ts

@@ -763,10 +763,10 @@ export interface TenantConfig {
   integrations?: readonly IntegrationDeclarationInput[];
   /**
    * The tenant's analytics policy for EU/EEA/UK/CH visitors and visitors whose region
-   * is unknown, from its `analytics.json`. Absent means `count-only`; only `full` and
-   * `none` are ever set. It reaches the browser through the server-stamped plan.
+   * is unknown, from its `analytics.json`. Absent means `ask`; only `count-only`, `full`
+   * and `none` are ever set. It reaches the browser through the server-stamped plan.
    */
-  euUkVisitors?: Exclude<EuUkVisitorPolicy, "count-only">;
+  euUkVisitors?: Exclude<EuUkVisitorPolicy, "ask">;
   /**
    * URL form and structured data, declared in `.tot/config.json` (validated by
    * `seoDeclarationProblems`, declared-tenant-config.mjs). A migrated store keeps the

package/packages/public-runtime/tests/fixtures/integration/campaign-token-corpus.ts

@@ -0,0 +1,75 @@
+import type {
+  ManagedAnalyticsCampaign,
+  ManagedAnalyticsCampaignField,
+  ManagedAnalyticsCampaignRejection,
+} from "../../../src/integration/managed-analytics-value-safety.js";
+
+/** One UTM set and the exact per-field outcome every analytics layer must agree on. */
+export interface CampaignCorpusCase {
+  name: string;
+  utm: ManagedAnalyticsCampaign;
+  kept: ManagedAnalyticsCampaign;
+  rejected: ManagedAnalyticsCampaignRejection[];
+}
+
+/** Date-stamped, brand and test labels that operators write by hand. */
+export const LEGITIMATE_CAMPAIGN_LABELS = [
+  "internal_attribution_20261027",
+  "ga4_receipt_20261027",
+  "gads_campaign_1234567",
+  "preview-test",
+  "brand_token_q4",
+] as const;
+
+/** A Google Ads ValueTrack `{campaignid}` shape (11 digits); not a live campaign. */
+export const VALUETRACK_CAMPAIGN_ID = "24398041332";
+
+function labelCase(field: ManagedAnalyticsCampaignField, label: string): CampaignCorpusCase {
+  const utm: ManagedAnalyticsCampaign = { source: "newsletter", medium: "email", [field]: label };
+  return { name: `${field} keeps ${label}`, utm, kept: utm, rejected: [] };
+}
+
+function rejectedCase(
+  name: string,
+  field: "campaign" | "term" | "content",
+  value: string,
+  reason: ManagedAnalyticsCampaignRejection["reason"],
+  source = "newsletter",
+): CampaignCorpusCase {
+  const base: ManagedAnalyticsCampaign = { source, medium: "cpc" };
+  return { name, utm: { ...base, [field]: value }, kept: base, rejected: [{ field, reason }] };
+}
+
+export const CAMPAIGN_TOKEN_CORPUS: readonly CampaignCorpusCase[] = [
+  ...(["source", "medium", "campaign", "term", "content"] as const).flatMap((field) =>
+    LEGITIMATE_CAMPAIGN_LABELS.map((label) => labelCase(field, label)),
+  ),
+  rejectedCase("a ValueTrack id is rejected beside source google", "campaign", VALUETRACK_CAMPAIGN_ID, "protected_value", "google"),
+  rejectedCase("a ValueTrack id is rejected in any field", "term", VALUETRACK_CAMPAIGN_ID, "protected_value", "google"),
+  rejectedCase("a US national number", "campaign", "2125550147", "protected_value", "google"),
+  rejectedCase("an 11-digit E.164 number without +", "campaign", "33612345678", "protected_value", "google"),
+  rejectedCase("a 12-digit E.164 number without +", "campaign", "447911123456", "protected_value", "google"),
+  rejectedCase("a 13-digit E.164 number without +", "campaign", "4915112345678", "protected_value", "google"),
+  rejectedCase("a 9-digit bare id", "campaign", "718234567", "protected_value", "google"),
+  rejectedCase("a card-length id stays blocked", "campaign", "4111111111111111", "protected_value", "google"),
+  rejectedCase("an embedded nine-digit run stays blocked", "campaign", "promo_212555014", "protected_value"),
+  rejectedCase("an email is not a token", "campaign", "shopper@example.com", "format"),
+  rejectedCase("a dashed US phone", "term", "212-555-0147", "protected_value"),
+  rejectedCase("an SSN", "content", "123-45-6789", "protected_value"),
+  rejectedCase("a provider secret", "campaign", ["sk", "live", "abcdefghijkl"].join("_"), "protected_value"),
+  rejectedCase("a cloud access key", "content", "AKIA" + "ABCDEFGHIJKLMNOP", "protected_value"),
+  rejectedCase("a bearer word", "campaign", "bearer-launch", "protected_value"),
+  rejectedCase("a password word", "term", "reset.password", "protected_value"),
+  rejectedCase("a secret word", "content", "secret_token", "protected_value"),
+  {
+    name: "one unsafe field costs only itself",
+    utm: { source: "newsletter", medium: "email", campaign: "ga4_receipt_20261027", content: "shopper@example.com" },
+    kept: { source: "newsletter", medium: "email", campaign: "ga4_receipt_20261027" },
+    rejected: [{ field: "content", reason: "format" }],
+  },
+];
+
+/** The raw values a case rejects, for asserting none of them reaches a sink or diagnostic. */
+export function rejectedCampaignValues(corpusCase: CampaignCorpusCase): string[] {
+  return corpusCase.rejected.map(({ field }) => corpusCase.utm[field]!);
+}

package/scripts/dev/ga4-gs2-canary.mjs

@@ -5,7 +5,11 @@
 // into an in-memory jar so GA4 reports the parent's visitor and session. This loads the BUILT
 // sandbox document and the CURRENT live gtag.js in headless Chromium, drives three page loads
 // (first visit, continuing, new session) through the real bind/configure protocol, and asserts
-// what gtag puts on /g/collect. Every collect request is ABORTED: nothing reaches Google.
+// what gtag puts on /g/collect. The frame carries the production box, and any event beyond
+// the page view and gtag's engagement timing (an automatic `scroll`) fails the canary. The first
+// load carries a landing click identifier, which must reach that page view's `dl` with every ad_*
+// signal still denied, and no other event.
+// Every collect request is ABORTED: nothing reaches Google.
 //
 // Needs the network (gtag.js), so it is a canary, not a CI test. Exit 0 = gtag behaves as the
 // seed expects; 1 = drift (the docs say what GA4 then reports); 2 = could not run.
@@ -16,9 +20,11 @@ import { createRequire } from "node:module";
 const storefrontRequire = createRequire(new URL("../../apps/storefront/package.json", import.meta.url));
 let chromium;
 let buildGoogleMeasurementSandboxHtml;
+let NATIVE_GA4_SANDBOX_FRAME_STYLE;
 try {
   ({ chromium } = storefrontRequire("@playwright/test"));
   ({ buildGoogleMeasurementSandboxHtml } = await import("../../apps/storefront/integrations/google-measurement-sandbox-asset.mjs"));
+  ({ NATIVE_GA4_SANDBOX_FRAME_STYLE } = await import("../../packages/public-runtime/src/integration/native-ga4-sandbox-asset.mjs"));
 } catch (error) {
   console.error(`ga4-gs2-canary: cannot run — ${error instanceof Error ? error.message : String(error)}`);
   process.exit(2);
@@ -26,33 +32,44 @@ try {
 
 const PARENT = "https://shop.canary.test";
 const FRAME = "https://www.shop.canary.test/platform/google-measurement/v2/sandbox.html";
-const MEASUREMENT_ID = "G-CANARY0001";
+// gtag fetches enhanced-measurement settings for the stream, so the scroll assertion is only
+// exercised against a stream with Scrolls on: pass its public measurement id as
+// GA4_CANARY_MEASUREMENT_ID. Collection stays aborted either way.
+const MEASUREMENT_ID = process.env.GA4_CANARY_MEASUREMENT_ID ?? "G-CANARY0001";
+// A labelled stand-in: GA4 never receives it, since every collect request is aborted.
+const CLICK_ID = "TEST_gclid_canary";
 const CLIENT_ID = "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d";
 const FIRST_SESSION_MS = Date.now() - 5 * 60 * 1000;
 const SECOND_SESSION_MS = Date.now();
 const seconds = (ms) => String(Math.floor(ms / 1000));
+const SETTLE_MS = 6_000;
+/** The page view this canary sends, plus gtag's own engagement timing. Anything else (a `scroll`) was fabricated in the frame. */
+const FRAME_EVENTS = new Set(["page_view", "user_engagement"]);
 
 const LOADS = [
   {
     name: "first visit",
     visitor: { clientId: CLIENT_ID, sessionId: FIRST_SESSION_MS, sessionState: "first_visit", sessionCount: 1 },
-    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: "1", _fv: "1" },
+    clickIds: { gclid: CLICK_ID },
+    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: "1", _fv: "1", dl: `${PARENT}/canary?gclid=${CLICK_ID}`, gcs: "G101" },
   },
   {
     name: "next page, same session",
     visitor: { clientId: CLIENT_ID, sessionId: FIRST_SESSION_MS, sessionState: "continuing", sessionCount: 1 },
-    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: null, _fv: null },
+    expect: { cid: CLIENT_ID, sid: seconds(FIRST_SESSION_MS), sct: "1", _ss: null, _fv: null, dl: `${PARENT}/canary`, gcs: "G101" },
   },
   {
     name: "return, new session",
     visitor: { clientId: CLIENT_ID, sessionId: SECOND_SESSION_MS, sessionState: "new_session", sessionCount: 2 },
-    expect: { cid: CLIENT_ID, sid: seconds(SECOND_SESSION_MS), sct: "2", _ss: "1", _fv: null },
+    expect: { cid: CLIENT_ID, sid: seconds(SECOND_SESSION_MS), sct: "2", _ss: "1", _fv: null, dl: `${PARENT}/canary`, gcs: "G101" },
   },
 ];
 
-const parentPage = (visitor) => `<!doctype html><body><script>
+/** @param {{ visitor: object, clickIds?: Record<string, string> }} load */
+const parentPage = ({ visitor, clickIds }) => `<!doctype html><body><script>
 const frame = document.createElement("iframe");
 frame.setAttribute("sandbox", "allow-scripts allow-same-origin");
+for (const [name, value] of Object.entries(${JSON.stringify(NATIVE_GA4_SANDBOX_FRAME_STYLE)})) frame.style.setProperty(name, value);
 frame.src = ${JSON.stringify(FRAME)};
 frame.addEventListener("load", () => {
   const channel = new MessageChannel();
@@ -61,7 +78,7 @@ frame.addEventListener("load", () => {
     canonicalOrigin: location.origin, analyticsConsent: "granted",
     governedProperties: { tenant: "canary", environment: "live", site_surface: "storefront" },
     visitor: ${JSON.stringify(visitor)} });
-  channel.port1.postMessage({ schemaVersion: 1, type: "page_view", path: "/canary" });
+  channel.port1.postMessage({ schemaVersion: 1, type: "page_view", path: "/canary"${clickIds ? `, clickIds: ${JSON.stringify(clickIds)}` : ""} });
 });
 document.body.append(frame);
 </script></body>`;
@@ -73,12 +90,14 @@ let gtagLoaded = false;
 try {
   const context = await browser.newContext();
   const pageViews = new Map();
+  const eventNames = new Set();
+  let clickIdOutsidePageView = false;
   let current = 0;
   await context.route("**/*", async (route) => {
     const request = route.request();
     const url = new URL(request.url());
     if (request.url().startsWith(FRAME)) return route.fulfill({ status: 200, contentType: "text/html", body: html });
-    if (url.origin === PARENT) return route.fulfill({ status: 200, contentType: "text/html", body: parentPage(LOADS[current].visitor) });
+    if (url.origin === PARENT) return route.fulfill({ status: 200, contentType: "text/html", body: parentPage(LOADS[current]) });
     if (url.host === "www.googletagmanager.com" && url.pathname === "/gtag/js") {
       gtagLoaded = true;
       return route.continue();
@@ -87,8 +106,10 @@ try {
       for (const line of [url.search.slice(1), ...(request.postData() ?? "").split("\n")].filter(Boolean)) {
         const params = new URLSearchParams(url.search);
         for (const [key, value] of new URLSearchParams(line)) params.set(key, value);
+        if (params.get("en")) eventNames.add(params.get("en"));
+        if (params.get("en") !== "page_view" && params.get("dl")?.includes(CLICK_ID)) clickIdOutsidePageView = true;
         if (params.get("en") === "page_view" && !pageViews.has(current)) {
-          pageViews.set(current, Object.fromEntries(["cid", "sid", "sct", "_ss", "_fv"].map((key) => [key, params.get(key)])));
+          pageViews.set(current, Object.fromEntries(["cid", "sid", "sct", "_ss", "_fv", "dl", "gcs"].map((key) => [key, params.get(key)])));
         }
       }
     }
@@ -98,6 +119,8 @@ try {
   for (current = 0; current < LOADS.length; current += 1) {
     await page.goto(`${PARENT}/?load=${current}`);
     for (let waited = 0; !pageViews.has(current) && waited < 15_000; waited += 250) await page.waitForTimeout(250);
+    // Enhanced measurement fires its automatic scroll within a few seconds of gtag loading.
+    await page.waitForTimeout(SETTLE_MS);
     await page.goto("about:blank");
     await page.waitForTimeout(500);
   }
@@ -115,6 +138,9 @@ try {
       }
       console.log(`${load.name}: ${JSON.stringify({ ...actual, cid: actual.cid === CLIENT_ID ? "<seeded>" : actual.cid })}`);
     });
+    const fabricated = [...eventNames].filter((name) => !FRAME_EVENTS.has(name));
+    if (fabricated.length > 0) failures.push(`events the storefront never sent left the frame: ${fabricated.join(", ")}`);
+    if (clickIdOutsidePageView) failures.push("a click identifier left the frame on an event other than its landing page view");
     if (cookies.length > 0) failures.push(`cookies written on the frame or parent origin: ${cookies.map((c) => c.name).join(", ")}`);
     if (failures.length > 0) {
       console.error("ga4-gs2-canary: DRIFT — gtag no longer honours the sandbox seed as expected:");
@@ -122,7 +148,7 @@ try {
       console.error("See docs/architecture/analytics-activation.md (GA4) for what GA4 reports in this state.");
       process.exitCode = 1;
     } else {
-      console.log("ga4-gs2-canary: OK — gtag reads the GS2 seed; cid, sid, sct, _ss and _fv match, no cookies written.");
+      console.log("ga4-gs2-canary: OK — gtag reads the GS2 seed; cid, sid, sct, _ss and _fv match, the landing gclid rides only its page view with ad consent denied (gcs=G101), no cookies written.");
     }
   }
 } finally {

package/scripts/tenant/validate.mjs

@@ -48,6 +48,7 @@ import {
 } from "../../agency-kit/tools/lib/tot-repo-mappings.mjs";
 import { isForbiddenPublicPath, publicBinaryFindings } from "../../agency-kit/tools/lib/public-binaries.mjs";
 import { pageSlugFindings } from "../../agency-kit/tools/lib/page-slugs.mjs";
+import { ANALYTICS_DECLARATION_FILE, analyticsDeclarationFindings } from "../../agency-kit/tools/lib/analytics-declaration.mjs";
 import { validateVisualParityClosure } from "../../packages/cli/src/visual-parity.mjs";
 import { declaredObligations, isRegulatedCompliance, validateDeclaredConfig } from "../../packages/cli/src/declared-config.mjs";
 
@@ -1200,6 +1201,14 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // analytics.json — the contract publication refuses; an unreadable file is an error, never "no analytics"
+  const analyticsPath = located(ANALYTICS_DECLARATION_FILE);
+  if (existsSync(analyticsPath)) {
+    for (const f of analyticsDeclarationFindings(readFileSync(analyticsPath, "utf8"))) {
+      findings.push(mk(ERROR, "analytics-declaration", rel(analyticsPath), f.message, f.remedy));
+    }
+  }
+
   // 3. content JSON — parse + blocks shape
   for (const name of ["home.json", "chrome.json"]) {
     const p = join(contentDir, name);