@tokenoftrust/storefront-runner 4.9.3 → 4.10.1

package/agency-kit/tools/lib/analytics-declaration.mjs

@@ -0,0 +1,299 @@
+// @ts-check
+/**
+ * The tenant `analytics.json` contract, for the surfaces that cannot load the platform's
+ * TypeScript: `tot validate`, the kit's validate-site, `scripts/tenant/validate.mjs` and
+ * materialize-tenant.
+ *
+ * The platform materializes the file with `materializeTenantAnalyticsDeclarations`
+ * (`packages/public-runtime/src/integration/tenant-analytics.ts`), which builds each destination
+ * through the reviewed adapter builder. This module reports the same `{ path, code }` set for any
+ * input; `agency-kit/tools/lib/fixtures/analytics-declarations.json` is run through both, so a
+ * drift on either side fails a test.
+ *
+ * Messages carry no value from the file — never an id, never a key's value — only the field path
+ * and a fixed explanation, so a finding is safe to print, log or forward.
+ *
+ * Pure: callers pass the file's text. `packages/cli/src/analytics-declaration.mjs` is a
+ * byte-identical copy (a test pins it).
+ */
+
+/** The tenant-owned file, at the tenant tree's root. */
+export const ANALYTICS_DECLARATION_FILE = "analytics.json";
+
+/** The current `analytics.json` contract version. */
+export const ANALYTICS_DECLARATION_SCHEMA_VERSION = 1;
+
+/** The stages a destination id may be declared for, in the platform's environment order. */
+export const ANALYTICS_STAGES = Object.freeze(["local", "candidate", "staged", "live"]);
+
+/** The `euUkVisitors` policies; `ask` is the default. */
+export const ANALYTICS_EU_UK_POLICIES = Object.freeze(["ask", "count-only", "full", "none"]);
+
+/**
+ * The first-class platform adapters a tenant may declare. Pinned against the platform's
+ * `PLATFORM_ADAPTERS` by `packages/public-runtime/tests/integration/tenant-analytics.test.ts`.
+ */
+export const ANALYTICS_ADAPTERS = Object.freeze([
+  Object.freeze({
+    adapterId: "platform.google-measurement",
+    maxDestinationsPerStage: 4,
+    idPattern: /^G-[A-Z0-9]{4,20}$/,
+    idLabel: "GA4 measurement id (e.g. G-XXXXXXX)",
+  }),
+  Object.freeze({
+    adapterId: "platform.meta-pixel",
+    maxDestinationsPerStage: 1,
+    idPattern: /^\d{10,20}$/,
+    idLabel: "Meta pixel id (10–20 digits)",
+  }),
+  Object.freeze({
+    adapterId: "platform.amplitude",
+    maxDestinationsPerStage: 1,
+    idPattern: /^(?=[a-f0-9]{32}$)(?=.*[a-f])[a-f0-9]+$/i,
+    idLabel: "Amplitude project API key (32 hexadecimal characters)",
+  }),
+]);
+
+const ANNOTATION_KEYS = ["$schema", "$comment", "$id"];
+const ROOT_KEYS = ["schemaVersion", "destinations", "euUkVisitors"];
+const DESTINATION_KEYS = ["adapter", "ids"];
+
+/**
+ * @typedef {Object} AnalyticsViolation
+ * @property {string} path  the offending field, e.g. `destinations[0].ids.live[1]`
+ * @property {string} code  a stable machine code, e.g. `format`, `unknown_field`
+ */
+
+/**
+ * @typedef {Object} AnalyticsFinding
+ * @property {string} path
+ * @property {string} code
+ * @property {string} message  value-free: the path, the code and a fixed explanation
+ * @property {string} remedy
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {Record<string, unknown>} obj
+ * @param {readonly string[]} allowed
+ * @param {string} base
+ * @param {AnalyticsViolation[]} out
+ */
+function unknownKeys(obj, allowed, base, out) {
+  for (const key of Object.keys(obj)) {
+    if (allowed.includes(key) || ANNOTATION_KEYS.includes(key)) continue;
+    out.push({ path: base ? `${base}.${key}` : key, code: "unknown_field" });
+  }
+}
+
+/**
+ * The adapter builder's per-stage id rules, with its paths re-anchored under the destination.
+ * @param {Record<string, unknown>} ids
+ * @param {(typeof ANALYTICS_ADAPTERS)[number]} adapter
+ * @param {string} base  `destinations[i]`
+ * @param {AnalyticsViolation[]} out
+ */
+function stageIdViolations(ids, adapter, base, out) {
+  /** @type {Map<string, string[]>} */
+  const valid = new Map();
+  for (const [stage, raw] of Object.entries(ids)) {
+    const at = `${base}.ids.${stage}`;
+    if (!ANALYTICS_STAGES.includes(stage)) {
+      out.push({ path: at, code: "unknown_enum" });
+      continue;
+    }
+    if (!Array.isArray(raw)) {
+      out.push({ path: at, code: "type" });
+      continue;
+    }
+    if (raw.length === 0) {
+      out.push({ path: at, code: "empty" });
+      continue;
+    }
+    if (raw.length > adapter.maxDestinationsPerStage) {
+      out.push({ path: at, code: "too_many_destinations" });
+      continue;
+    }
+    let stageOk = true;
+    raw.forEach((id, index) => {
+      if (typeof id !== "string" || id.length === 0) {
+        out.push({ path: `${at}[${index}]`, code: "type" });
+        stageOk = false;
+        return;
+      }
+      if (!adapter.idPattern.test(id)) {
+        out.push({ path: `${at}[${index}]`, code: "format" });
+        stageOk = false;
+      }
+    });
+    if (!stageOk) continue;
+    if (new Set(raw).size !== raw.length) {
+      out.push({ path: at, code: "duplicate" });
+      continue;
+    }
+    valid.set(stage, /** @type {string[]} */ (raw));
+  }
+  const live = valid.get("live");
+  if (live === undefined) {
+    out.push({ path: `${base}.ids.live`, code: "required" });
+    return;
+  }
+  for (const stage of ANALYTICS_STAGES) {
+    if (stage === "live") continue;
+    (valid.get(stage) ?? []).forEach((id, index) => {
+      if (live.includes(id)) out.push({ path: `${base}.ids.${stage}[${index}]`, code: "non_live_reuses_live_id" });
+    });
+  }
+}
+
+/**
+ * Every violation in an already-parsed `analytics.json` value. `undefined`/`null` (no file) is
+ * the undeclared norm and has none.
+ * @param {unknown} value
+ * @returns {AnalyticsViolation[]}
+ */
+export function analyticsDeclarationViolations(value) {
+  /** @type {AnalyticsViolation[]} */
+  const out = [];
+  if (value === undefined || value === null) return out;
+  if (!isPlainObject(value)) {
+    out.push({ path: "(root)", code: "type" });
+    return out;
+  }
+  unknownKeys(value, ROOT_KEYS, "", out);
+  if ("euUkVisitors" in value && !ANALYTICS_EU_UK_POLICIES.includes(/** @type {string} */ (value.euUkVisitors))) {
+    out.push({ path: "euUkVisitors", code: "unknown_enum" });
+  }
+  if ("schemaVersion" in value && value.schemaVersion !== ANALYTICS_DECLARATION_SCHEMA_VERSION) {
+    out.push({ path: "schemaVersion", code: "unsupported_version" });
+  }
+  const destinations = value.destinations;
+  if (!Array.isArray(destinations)) {
+    out.push({ path: "destinations", code: "type" });
+    return out;
+  }
+  /** @type {Set<string>} */
+  const seenAdapters = new Set();
+  destinations.forEach((destination, index) => {
+    const base = `destinations[${index}]`;
+    if (!isPlainObject(destination)) {
+      out.push({ path: base, code: "type" });
+      return;
+    }
+    unknownKeys(destination, DESTINATION_KEYS, base, out);
+    const adapterId = destination.adapter;
+    if (typeof adapterId !== "string" || adapterId.length === 0) {
+      out.push({ path: `${base}.adapter`, code: "type" });
+      return;
+    }
+    const ids = destination.ids;
+    if (!isPlainObject(ids)) {
+      out.push({ path: `${base}.ids`, code: "type" });
+      return;
+    }
+    if (seenAdapters.has(adapterId)) {
+      out.push({ path: `${base}.adapter`, code: "duplicate" });
+      return;
+    }
+    seenAdapters.add(adapterId);
+    const adapter = ANALYTICS_ADAPTERS.find((a) => a.adapterId === adapterId);
+    if (!adapter) {
+      out.push({ path: `${base}.adapter`, code: "unknown_adapter" });
+      return;
+    }
+    stageIdViolations(ids, adapter, base, out);
+  });
+  return out;
+}
+
+/**
+ * Parse `analytics.json` text. Unparseable text is a `(root)` `invalid_json` violation, never an
+ * absent file: a declaration that cannot be read must refuse, not publish with no analytics.
+ * @param {string} text
+ * @returns {{ ok: true, value: unknown } | { ok: false, violations: AnalyticsViolation[] }}
+ */
+export function parseAnalyticsDeclaration(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false, violations: [{ path: "(root)", code: "invalid_json" }] };
+  }
+}
+
+const ADAPTER_IDS = ANALYTICS_ADAPTERS.map((a) => a.adapterId).join(", ");
+const ID_FORMATS = ANALYTICS_ADAPTERS.map((a) => `${a.adapterId}: ${a.idLabel}`).join("; ");
+
+/**
+ * A fixed, value-free explanation and remedy for a violation.
+ * @param {AnalyticsViolation} violation
+ * @returns {{ message: string, remedy: string }}
+ */
+export function analyticsViolationText({ path, code }) {
+  switch (code) {
+    case "invalid_json":
+      return { message: "analytics.json is not valid JSON", remedy: "fix the JSON syntax" };
+    case "type":
+      return {
+        message: "has the wrong type",
+        remedy: 'use { "schemaVersion": 1, "destinations": [{ "adapter": "<adapter id>", "ids": { "live": ["<id>"] } }] }',
+      };
+    case "unknown_field":
+      return { message: "is not an analytics.json field", remedy: "remove it; analytics.json is a closed contract" };
+    case "unknown_enum":
+      return path === "euUkVisitors"
+        ? { message: "is not an EU/UK visitor policy", remedy: `use one of: ${ANALYTICS_EU_UK_POLICIES.join(", ")}` }
+        : { message: "is not a stage", remedy: `use one of: ${ANALYTICS_STAGES.join(", ")}` };
+    case "unsupported_version":
+      return { message: "is not a supported schemaVersion", remedy: `set it to ${ANALYTICS_DECLARATION_SCHEMA_VERSION}` };
+    case "unknown_adapter":
+      return { message: "is not a first-class analytics adapter", remedy: `use one of: ${ADAPTER_IDS}` };
+    case "empty":
+      return { message: "names no destination id", remedy: "name at least one id, or remove the stage" };
+    case "too_many_destinations":
+      return { message: "names more destination ids than this adapter accepts per stage", remedy: "remove the extra ids" };
+    case "format":
+      return { message: "is not a valid destination id for this adapter", remedy: `use the adapter's id format (${ID_FORMATS})` };
+    case "duplicate":
+      return path.endsWith(".adapter")
+        ? { message: "names an adapter an earlier destination already names", remedy: "declare each adapter once, with all of its ids" }
+        : { message: "names the same destination id twice", remedy: "list each id once" };
+    case "required":
+      return { message: "has no valid live destination id", remedy: "declare a valid live id for every destination" };
+    case "non_live_reuses_live_id":
+      return {
+        message: "reuses a live destination id, so non-live traffic would reach the live property",
+        remedy: "use a separate test id, or leave the stage unset",
+      };
+    default:
+      return { message: "is invalid", remedy: "see docs/architecture/analytics-activation.md" };
+  }
+}
+
+/**
+ * Every violation in an `analytics.json` file's text. A file that is present but holds `null` is
+ * a `(root)` `type` violation: only an absent file declares nothing.
+ * @param {string} text
+ * @returns {AnalyticsViolation[]}
+ */
+export function analyticsDeclarationTextViolations(text) {
+  const parsed = parseAnalyticsDeclaration(text);
+  if (!parsed.ok) return [...parsed.violations];
+  if (parsed.value === null) return [{ path: "(root)", code: "type" }];
+  return analyticsDeclarationViolations(parsed.value);
+}
+
+/**
+ * Every finding in an `analytics.json` file's text, each value-free.
+ * @param {string} text
+ * @returns {AnalyticsFinding[]}
+ */
+export function analyticsDeclarationFindings(text) {
+  return analyticsDeclarationTextViolations(text).map((violation) => {
+    const { message, remedy } = analyticsViolationText(violation);
+    return { ...violation, message: `${violation.path}: [${violation.code}] ${message}`, remedy };
+  });
+}

package/apps/storefront/package.json

@@ -14,7 +14,7 @@
     "preview": "wrangler dev",
     "typecheck": "astro check && tsc --noEmit",
     "astro": "astro",
-    "test": "NODE_OPTIONS=--experimental-sqlite vitest run --exclude src/lib/integrations/apps/v84CleanCloneReplay.test.ts --exclude src/lib/integrations/apps/v84NonportableRouteDogfood.test.ts --exclude src/lib/integrations/apps/v84CloneLifecycleEvidence.test.ts && NODE_OPTIONS=--experimental-sqlite vitest run src/lib/integrations/apps/v84CleanCloneReplay.test.ts src/lib/integrations/apps/v84NonportableRouteDogfood.test.ts src/lib/integrations/apps/v84CloneLifecycleEvidence.test.ts --fileParallelism=false && pnpm run test:pipeline && pnpm run test:pipeline-faults",
+    "test": "NODE_OPTIONS=--experimental-sqlite node ../../scripts/vitest-run.mjs run --exclude src/lib/integrations/apps/v84CleanCloneReplay.test.ts --exclude src/lib/integrations/apps/v84NonportableRouteDogfood.test.ts --exclude src/lib/integrations/apps/v84CloneLifecycleEvidence.test.ts && NODE_OPTIONS=--experimental-sqlite node ../../scripts/vitest-run.mjs run src/lib/integrations/apps/v84CleanCloneReplay.test.ts src/lib/integrations/apps/v84NonportableRouteDogfood.test.ts src/lib/integrations/apps/v84CloneLifecycleEvidence.test.ts --fileParallelism=false && pnpm run test:pipeline && pnpm run test:pipeline-faults",
     "depcruise": "depcruise src --config .runner-dependency-cruiser.cjs"
   },
   "dependencies": {

package/apps/storefront/src/lib/access/shared/cspStaticHashes.ts

@@ -19,7 +19,7 @@ export const STATIC_SCRIPT_HASHES: readonly string[] = [
   "'sha256-YicfxUFBkKrQapZ/tzZKlaKTdNHgwVfv7y2Wa0NC6/k='",
   "'sha256-eIXWvAmxkr251LJZkjniEK5LcPF3NkapbJepohwYRIc='",
   "'sha256-elMLh/6Oubj8u9FRLwZLyRa6TqKikGs75mf0jfWcoxI='",
-  "'sha256-bANHtvoDkw4GnpBynM5Ib1cxdoDeNsGkPhPnDEphW3Y='",
+  "'sha256-MG9XnFVbN8UmLcNws9A8ckOhQJI+MnAKxpCI7oBMS3Q='",
 ];
 
 export const STATIC_STYLE_HASHES: readonly string[] = [

package/apps/storefront/src/lib/compliance/shared/visitorRegionCookie.ts

@@ -12,7 +12,7 @@
  *   - a CloudFront-forwarded Tier 3 request (its `cf` describes CloudFront, not the
  *     viewer);
  *   - no `request.cf` at all.
- * The page then keeps whatever class it already holds, or none (count-only).
+ * The page then keeps whatever class it already holds, or none (the EU/UK policy).
  *
  * The local dev loop's `request.cf` comes from the dev runtime's cached `cf.json`, which
  * describes the developer's own location. `?tot_region=eu|x|u` overrides it so both

package/apps/storefront/src/lib/integrations/integration/tenantAnalyticsDeclarations.ts

@@ -1,228 +1,68 @@
 /**
- * Tenant-owned analytics declaration surface (TIER 1).
+ * Runtime read of a tenant's own `analytics.json` (TIER 1) for the render hot path.
  *
- * Today a tenant cannot declare a measurement destination from its OWN tree: the
- * declaration lives in `tenant.integrations` (apps/storefront/src/config/tenants.ts),
- * which is platform code a tenant may not touch (customization golden rule #1). So a
- * merchant must file a request for what should be a self-serve, versioned, publishable
- * edit — exactly like `theme.json` or `content/*`.
- *
- * This module is the tenant-tree producer that closes that gap. A tenant commits an
- * `analytics.json` in its own tree (the tenant-owned surface, `tenants/<id>/**`), and
- * this materializes it into the SAME already-consumed declaration seam
- * ({@link IntegrationDeclarationInput}[], read by
- * {@link loadTenantIntegrationDeclarations} and merged into the render plan by the
- * interim bridge). It adds NO new runtime: it is a THIRD producer into an existing
- * consumer, alongside the platform-authored `tenant.integrations` and the D1-backed
- * managed installs.
- *
- * The heavy validation is NOT hand-rolled — each declared destination is built by the
- * shipped, 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. That is the whole point: a tenant supplies only public
- * per-stage destination ids and gets a working, consent-gated, CSP-clean, non-live-safe
- * measurement integration with no renderer change.
- *
- * Two callers, one core:
- *   - PUBLISH validation — {@link materializeTenantAnalyticsDeclarations} returns
- *     structured {@link ContractViolation}s so the ship/customization pipeline can
- *     REFUSE an invalid `analytics.json` with an actionable, per-field message, exactly
- *     as it refuses an invalid `theme.json`.
- *   - RUNTIME materialization — {@link loadTenantAnalyticsDeclarations} is fail-closed:
- *     a missing or (defensively) invalid file yields the empty set, never a throw, so an
- *     undeclared tenant resolves the environment-only plan and a byte-identical page.
+ * The contract and its materializer live in `@tot/public-runtime`
+ * ({@link materializeTenantAnalyticsDeclarations}); publish validation refuses an invalid file
+ * before it can reach here. This loader is the defensive last line: fail-closed and value-free.
  */
 import {
-  buildPlatformAdapterDeclaration,
-  ENVIRONMENT_SCHEMA_VERSION,
-  Violations,
-  isEuUkVisitorPolicy,
-  isPlainObject,
-  rejectUnknownKeys,
-  type BrowserEnvironment,
-  type ContractViolation,
+  describeTenantAnalyticsViolations,
+  materializeTenantAnalyticsDeclarations,
   type IntegrationDeclarationInput,
-  type TenantConfig,
+  type TenantAnalyticsMaterialization,
 } from "@tot/public-runtime";
 
-/** The tenant-owned file that declares measurement destinations, in the tenant tree. */
-export const TENANT_ANALYTICS_FILE = "analytics.json";
-
-/** The current `analytics.json` contract version. */
-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 `count-only` default. Absent
-   * whenever `ok` is false, so an invalid file never widens EU/UK collection.
-   */
-  euUkVisitors?: TenantConfig["euUkVisitors"];
-  /** 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;
+function warnDeclaration(summary: string, violations: readonly { path: string; code: string }[]): void {
+  try {
+    console.warn(`[diag:analytics:declaration] ${summary}`, JSON.stringify({ violations }));
+  } catch {
+    /* diagnostics must never break the caller */
   }
-  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 "count-only" (the default), "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[] = [];
-  destinationsRaw.forEach((destinationRaw, index) => {
-    const destination = readDestination(destinationRaw, index, v);
-    if (!destination) return;
-    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: [],
-    ...(euUkVisitors === "full" || euUkVisitors === "none" ? { euUkVisitors } : {}),
-  };
-}
-
-/**
- * Read a tenant's already-materialized analytics declarations for the render hot path,
- * fail-closed: a missing OR invalid file yields the empty set (never throws), so an
- * undeclared tenant resolves the environment-only plan and a defensively-invalid file
- * darks its own analytics rather than the page. Publish validation
- * ({@link materializeTenantAnalyticsDeclarations}) is what keeps an invalid file from
- * ever reaching here.
+ * Read a tenant's already-materialized analytics declarations, fail-closed: a missing OR
+ * invalid file yields the empty set (never throws), so an undeclared tenant resolves the
+ * environment-only plan and an invalid file darks its own analytics rather than the page.
+ * A file that is present but holds `null` is invalid; only an absent file (`undefined`)
+ * declares nothing.
+ *
+ * `installed` is what the tenant already declares in platform code. The plan resolves an app
+ * at most once and refuses the whole plan on a repeat, so a destination whose adapter is
+ * already installed there is dropped, keeping the platform's install and the rest of the plan.
+ *
+ * Neither a refusal nor a drop is silent: each emits one `[diag:analytics:declaration]`
+ * warning naming the field path and code. The warning carries no value from the file and no
+ * tenant or destination identifier.
  */
 export function loadTenantAnalyticsDeclarations(
   raw: unknown,
   tenantPublicId: string,
   canonicalHost: string,
+  installed: readonly IntegrationDeclarationInput[] = [],
 ): Pick<TenantAnalyticsMaterialization, "declarations" | "euUkVisitors"> {
-  const { declarations, euUkVisitors } = materializeTenantAnalyticsDeclarations({
+  if (raw === null) {
+    warnDeclaration("analytics.json refused; no analytics declared", [{ path: "(root)", code: "type" }]);
+    return { declarations: [] };
+  }
+  const { ok, declarations, euUkVisitors, violations } = materializeTenantAnalyticsDeclarations({
     raw,
     tenantPublicId,
     canonicalHost,
   });
-  return euUkVisitors ? { declarations, euUkVisitors } : { declarations };
+  if (!ok) {
+    warnDeclaration("analytics.json refused; no analytics declared", describeTenantAnalyticsViolations(violations));
+  }
+  const installedAppIds = new Set(installed.map((declaration) => declaration.manifest.app.id));
+  const dropped: { path: string; code: string }[] = [];
+  // A valid file materializes one declaration per destination, in order.
+  const kept = declarations.filter((declaration, index) => {
+    if (!installedAppIds.has(declaration.manifest.app.id)) return true;
+    dropped.push({ path: `destinations[${index}].adapter`, code: "platform_installed" });
+    return false;
+  });
+  if (dropped.length > 0) {
+    warnDeclaration("analytics.json destination dropped; the platform already installs its adapter", dropped);
+  }
+  return euUkVisitors ? { declarations: kept, euUkVisitors } : { declarations: kept };
 }