@tokenoftrust/storefront-runner 2.0.17 → 2.0.18

package/apps/storefront/src/lib/apps/gtmMigrationDraft.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure, transport-free bridge from an uploaded GTM export to a REVIEWABLE
+ * migration-draft PROPOSAL — the connective tissue that makes the self-serve
+ * import→draft→review→install flow usable by a tenant developer.
+ *
+ * The analyze surface returns only a REDACTED report, so a developer can never
+ * reconstruct the `createMigrationDraft` body (proposedAdapterId /
+ * proposedConfiguration / findings) from it — those derive from the UNREDACTED
+ * container. This helper runs the same safe pipeline analyze uses
+ * (`parseGtmExport` → `buildMigrationGraph` → `classifyMigration`) and then the
+ * pure `generateDisabledMigrationDraft`, returning exactly the
+ * `CreateMigrationDraftBody` the developer submits, plus an inert review summary.
+ *
+ * SAFE-BY-CONSTRUCTION: the produced draft is `enabled:false, publishes:false`;
+ * the proposal carries only validator-safe values (the generator validates its
+ * own output against the pinned schema, and throws rather than emit an invalid
+ * one). Nothing here writes, enables, or publishes — it returns a plain data
+ * object, like the analyze builder.
+ */
+import {
+  parseGtmExport,
+  buildMigrationGraph,
+  classifyMigration,
+  generateDisabledMigrationDraft,
+  NO_ADAPTER_SELECTED_ID,
+  type CreateMigrationDraftBody,
+  type GtmViolation,
+  type MigrationFindingCode,
+} from "@tot/public-runtime";
+
+/** The inert, review-friendly summary of what installing the proposal would stage. */
+export interface GtmDraftProposalSummary {
+  /** Whether a managed-analytics adapter was matched (false = nothing auto-portable). */
+  readonly adapterSelected: boolean;
+  /** Count of GTM objects that mapped confidently into the managed adapter. */
+  readonly mappedCount: number;
+  /** Count of GTM objects that could not be automatically ported (needs review). */
+  readonly unresolvedCount: number;
+  /** Whether a destination id was carried into the proposed configuration. */
+  readonly destinationConfigured: boolean;
+  /** Stable redacted finding codes (no source text). */
+  readonly findings: MigrationFindingCode[];
+}
+
+export interface GtmProposeOk {
+  readonly ok: true;
+  readonly correlationId: string;
+  /** The exact body a caller POSTs to `createMigrationDraft`. */
+  readonly proposal: CreateMigrationDraftBody;
+  readonly summary: GtmDraftProposalSummary;
+}
+
+export interface GtmProposeErr {
+  readonly ok: false;
+  readonly correlationId: string;
+  readonly error: string;
+  readonly violations: GtmViolation[];
+}
+
+/**
+ * Parse + graph + classify an uploaded export into a disabled migration-draft
+ * PROPOSAL, or return the structured parse violations with a stable, safe error.
+ * NEVER throws on bad input, NEVER executes any part of the export.
+ *
+ * `draftId` is a placeholder the pure generator requires for its own provenance
+ * stamp; the authoritative draft id is assigned server-side by
+ * `createMigrationDraft`, so the caller only reads the returned `proposal`.
+ */
+export function proposeGtmMigrationDraft(
+  input: string | Uint8Array,
+  opts: { correlationId: string; generatedAt: string; draftId: string },
+): GtmProposeOk | GtmProposeErr {
+  const parsed = parseGtmExport(input);
+  if (!parsed.ok) {
+    return {
+      ok: false,
+      correlationId: opts.correlationId,
+      error: "The uploaded file is not a valid GTM container export.",
+      violations: parsed.violations,
+    };
+  }
+  const graph = buildMigrationGraph(parsed.container);
+  const disposition = classifyMigration(graph);
+  const result = generateDisabledMigrationDraft({
+    container: parsed.container,
+    graph,
+    disposition,
+    provenance: { draftId: opts.draftId, generatedAt: opts.generatedAt },
+  });
+  const { proposedAdapterId, proposedConfiguration, findings } = result.draft;
+  return {
+    ok: true,
+    correlationId: opts.correlationId,
+    proposal: { proposedAdapterId, proposedConfiguration, findings },
+    summary: {
+      adapterSelected: proposedAdapterId !== NO_ADAPTER_SELECTED_ID,
+      mappedCount: result.mappedConcepts.length,
+      unresolvedCount: result.unresolvedInventory.length,
+      destinationConfigured: findings.includes("ga4-destination-id-configured"),
+      findings,
+    },
+  };
+}

package/apps/storefront/src/lib/auth/loginGate.ts

@@ -244,6 +244,11 @@ export function isAdminPath(pathname: string): boolean {
  *   - every `/api/` route (tenant-state mutation). Genuinely-public API endpoints
  *     are already gate-exempt via {@link isPublicPath}/{@link isAuthPath}, so
  *     excluding all of `/api/` here costs nothing and fails safe.
+ *
+ * Every entry is matched in BOTH addressing forms — bare (`/api/...`) and
+ * tenant-prefixed (`/<tenant>/api/...`) — because the storefront serves the same
+ * route under both, so matching only one leaves the other reachable on a token or
+ * bypass header alone.
  */
 export function isBypassPrivilegedPath(pathname: string): boolean {
   if (isAdminPath(pathname)) return true;
@@ -252,6 +257,7 @@ export function isBypassPrivilegedPath(pathname: string): boolean {
   if (pathname === "/dev" || pathname.startsWith("/dev/")) return true;
   if (/^\/[^/]+\/dev(?:\/|$)/.test(pathname)) return true;
   if (pathname === "/api" || pathname.startsWith("/api/")) return true;
+  if (/^\/[^/]+\/api(?:\/|$)/.test(pathname)) return true;
   return false;
 }
 
@@ -281,6 +287,19 @@ export interface LoginGateInput {
    * (admin, cockpit, /api) are never bypassed regardless of this flag.
    */
   qaBypass?: boolean;
+  /**
+   * True when the request presented a signed, unexpired customization-preview
+   * token (`?__preview=` or the `tot_preview` cookie) whose `tenantId` claim is
+   * THIS request's tenant. The token is HMAC-signed with
+   * `CUSTOMIZATION_PREVIEW_SECRET` and tenant-bound, so it is not client-forgeable
+   * and one tenant's token never admits a viewer to another's content.
+   *
+   * Available to EVERY tenant: previewing an unpublished storefront is platform
+   * functionality, not a property of which tenant is being viewed. Passes the gate
+   * for PUBLIC CONTENT paths only; {@link isBypassPrivilegedPath} paths (admin,
+   * cockpit, /api) still require a real session.
+   */
+  previewTokenValid?: boolean;
 }
 
 /**
@@ -305,6 +324,12 @@ export function evaluateLoginGate(input: LoginGateInput): LoginGateDecision {
   // public content only. NEVER for admin/cockpit/api — that guard lives here (not
   // just in middleware) so /admin stays gated even if the flag is set upstream.
   if (input.qaBypass && !isBypassPrivilegedPath(input.pathname)) return { action: "pass" };
+  // Customization preview: a signed, tenant-bound preview token admits a viewer to
+  // that tenant's public content on any tenant. Same privileged-path exclusion as
+  // the QA bypass — admin/cockpit/api are never reachable on a token alone.
+  if (input.previewTokenValid && !isBypassPrivilegedPath(input.pathname)) {
+    return { action: "pass" };
+  }
   if (input.hasValidSession) return { action: "pass" };
   const next = input.pathname + (input.search ?? "");
   return { action: "redirect", location: `/auth/login?next=${encodeURIComponent(next)}` };

package/apps/storefront/src/lib/checkoutCommerce.ts

@@ -14,7 +14,7 @@
  */
 import type { TenantConfig, ResolvedManagedCheckout } from "@tot/public-runtime";
 import { resolveManagedCheckout } from "@tot/public-runtime";
-import { readEnv } from "@/lib/env";
+import { readEnv } from "@/lib/runtimeEnv";
 
 /**
  * Resolve the effective checkout facts for a tenant, or null when the tenant has

package/apps/storefront/src/lib/compliance/enforcement.ts

@@ -19,7 +19,7 @@ import type {
 } from "@tot/public-runtime";
 import { enforcementSignals } from "@tot/public-runtime";
 import { readEnv } from "@/lib/env";
-import { COMPLIANCE_RULESETS } from "@/config/compliance/rulesets";
+import { COMPLIANCE_RULE_PROFILES } from "@/config/compliance/rulesets";
 
 /** True when the tenant sells age/nicotine-restricted goods (drives fail-closed). */
 export function isRegulatedTenant(
@@ -55,6 +55,26 @@ export function isSandboxVerificationProvider(
   return !!provider && SANDBOX_VERIFICATION_PROVIDERS.has(provider.toLowerCase());
 }
 
+/**
+ * The LIVE Token of Trust verification provider. When `TOT_VERIFICATION_PROVIDER`
+ * resolves to this, `/api/compliance/preflight` calls the real ToT verification
+ * API server-side (`@/lib/verification/totVerificationClient`) and derives the
+ * verification state from that call ALONE — never from a client-supplied
+ * `verification` field and never from the front-door affirmation.
+ *
+ * Deliberately DISJOINT from {@link SANDBOX_VERIFICATION_PROVIDERS}: the
+ * affirmation-simulates-verification shortcut must be unreachable under the live
+ * provider (asserted in enforcement.test.ts).
+ */
+export const LIVE_TOT_VERIFICATION_PROVIDER = "tot";
+
+/** True when the resolved provider is the live ToT verification integration. */
+export function isLiveTotVerificationProvider(
+  provider: string | undefined | null,
+): boolean {
+  return !!provider && provider.toLowerCase() === LIVE_TOT_VERIFICATION_PROVIDER;
+}
+
 /**
  * The PACT reporting CAPTURE sink status. The record BUILDER
  * (`buildPactReportRecord`) ships in this unit and the capture point is wired at
@@ -73,8 +93,10 @@ const PACT_REPORTING_CAPTURE_WIRED = true;
 export async function resolveTenantRuleset(
   tenant: Pick<TenantConfig, "tenant_id" | "compliance">,
 ): Promise<ComplianceRuleset | null> {
-  const base = COMPLIANCE_RULESETS[tenant.tenant_id];
-  if (!base) return null;
+  const profile = tenant.compliance?.ruleProfile;
+  const buildRuleset = profile ? COMPLIANCE_RULE_PROFILES[profile] : undefined;
+  if (!buildRuleset) return null;
+  const base = buildRuleset(tenant.tenant_id);
   const provider = (await readEnv("TOT_VERIFICATION_PROVIDER")) || undefined;
   return {
     ...base,

package/apps/storefront/src/lib/d1/schema-apps.ts

@@ -206,6 +206,50 @@ export const trackingTenantDatabases = sqliteTable(
   }),
 );
 
+// --- Managed-analytics test destinations -------------------------------------
+// A tenant-owned, NON-LIVE-ONLY destination a developer registers to prove
+// exactly-once delivery for a new marketing action before wiring a real vendor
+// adapter (GA4/Meta/Amplitude fire directly to the vendor with no server-side
+// readback). `environment` is never `live` — enforced by the managed-analytics
+// service, not by this table. Deliberately its OWN table, not `app_installs` —
+// this is not an integration install (no adapter, no manifest, no CSP/consent
+// plan); it is a disposable proving fixture for the action registry.
+export const testDestinations = sqliteTable(
+  "test_destinations",
+  {
+    destinationId: text("destination_id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    environment: text("environment").notNull(),
+    createdAt: text("created_at").notNull(),
+  },
+  (t) => ({
+    idxTestDestinationsTenant: index(
+      "idx_test_destinations_tenant",
+    ).on(t.tenantId),
+  }),
+);
+
+// The delivered-event ledger a test destination reads back. Keyed by
+// (destination_id, event_id): a retried/duplicate delivery of the same event id
+// is `INSERT OR IGNORE`, so the row a caller reads back always reflects the
+// FIRST delivery only — the proof that delivery landed exactly once.
+export const testDestinationDeliveries = sqliteTable(
+  "test_destination_deliveries",
+  {
+    destinationId: text("destination_id").notNull(),
+    eventId: text("event_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    actionName: text("action_name").notNull(),
+    deliveredAt: text("delivered_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.destinationId, t.eventId] }),
+    idxTestDestinationDeliveriesTenant: index(
+      "idx_test_destination_deliveries_tenant",
+    ).on(t.tenantId),
+  }),
+);
+
 // --- Webhook event spine ----------------------------------------------------
 // Immutable event log. `id` is the semantic event id we mint — distinct from
 // any per-delivery wire envelope id (see `webhookDeliveries.deliveryId` below).

package/apps/storefront/src/lib/env.ts

@@ -1,123 +1,25 @@
 /**
- * Runtime env access that works in BOTH contexts:
- *   - `astro dev` (Node): reads import.meta.env / process.env.
- *   - Cloudflare Workers (prod): reads the `cloudflare:workers` env module.
+ * The FULL runtime binding surface: everything in `./runtimeEnv.js` plus the D1
+ * binding. Control-plane code imports this one and gets all of it.
  *
- * Astro v6+/@astrojs/cloudflare v14 REMOVED `Astro.locals.runtime.env`; the
- * supported path is `import { env } from "cloudflare:workers"`. That module only
- * exists in the worker runtime, so we import it lazily + guarded and fall back
- * to build-time env in dev. See DECISIONS.md.
+ * The D1 accessor lives HERE rather than in `runtimeEnv.js` because ADR 0013
+ * keeps a live control-plane read off a tenant's public path, and a
+ * dependency-cruiser fence can only forbid a MODULE — never a symbol. Splitting
+ * `readD1` onto its own import graph is what gives
+ * `public-render-no-request-time-d1` (.dependency-cruiser.cjs) something to
+ * name: the public-render branch reaches `runtimeEnv.js` for the bindings that
+ * serve published bytes (KV cache, R2 bundles) and cannot reach this module at
+ * all, so a request-time D1 handle is unobtainable there rather than merely
+ * unused.
  */
 import type { D1Like } from "./d1/catalog.js";
 
-let workerEnv: Record<string, unknown> | null | undefined;
+export * from "./runtimeEnv.js";
 
-async function getWorkerEnv(): Promise<Record<string, unknown> | null> {
-  if (workerEnv !== undefined) return workerEnv;
-  try {
-    // @ts-expect-error — virtual module, only resolvable in the Workers runtime.
-    const mod = await import("cloudflare:workers");
-    workerEnv = (mod.env ?? null) as Record<string, unknown> | null;
-  } catch {
-    workerEnv = null;
-  }
-  return workerEnv;
-}
-
-function fromBuild(key: string): string | undefined {
-  const meta = import.meta.env as Record<string, string | undefined>;
-  if (meta[key] != null) return meta[key];
-  if (typeof process !== "undefined" && process.env && process.env[key] != null) {
-    return process.env[key];
-  }
-  return undefined;
-}
-
-export async function readEnv(key: string): Promise<string | undefined> {
-  const w = await getWorkerEnv();
-  const wv = w?.[key];
-  if (typeof wv === "string" && wv.length) return wv;
-  return fromBuild(key);
-}
-
-/** The slice of the Workers ExecutionContext runAfterResponse needs — the
- *  @astrojs/cloudflare adapter exposes it to routes as `locals.cfContext`. */
-export interface CfExecutionContextLike {
-  waitUntil(promise: Promise<unknown>): void;
-}
-
-/**
- * Run `work` PAST the response — the request's `ExecutionContext.waitUntil`
- * when the caller passes it, else a detached floating promise (dev/Node). For
- * webhook RECEIVERS that must ACK fast: the upstream forwarder (tot-mcp
- * gitea-webhook proxy) aborts its forward at 15s and Gitea bounds its delivery
- * wait too, while a real reconcile takes tens of seconds — running it inside
- * the request meant every healthy reconcile was killed mid-flight and recorded
- * as `forward_failed` (a layer of Trello 13075, behind the auth fix).
- *
- * CALLERS MUST PASS `locals.cfContext` (the @astrojs/cloudflare adapter's
- * per-request ExecutionContext, `createLocals: { cfContext: ctx }`): in the
- * Workers runtime a merely-floating promise is CANCELLED the moment the
- * response returns — an earlier revision here imported `waitUntil` from
- * `cloudflare:workers` (not exported by this adapter/runtime version), silently
- * degraded to the floating promise, and the async reconcile died unobserved
- * right after its 202. The floating-promise branch is a DEV-ONLY fallback.
- * Errors are the caller's to handle inside `work` (this never throws).
- */
-export function runAfterResponse(
-  work: Promise<unknown>,
-  cfContext?: CfExecutionContextLike | null,
-): void {
-  const swallowed = work.catch(() => {});
-  if (cfContext && typeof cfContext.waitUntil === "function") {
-    cfContext.waitUntil(swallowed);
-    return;
-  }
-  // dev/Node only — in the Workers runtime this promise would be cancelled at
-  // response end, which is exactly the bug the parameter above exists to avoid.
-  void swallowed;
-}
-
-/** KV binding for the newsletter stub / tenant cache, if present in the runtime. */
-export async function readKv(binding: string): Promise<KVNamespace | undefined> {
-  const w = await getWorkerEnv();
-  const b = w?.[binding];
-  return (b as KVNamespace | undefined) ?? undefined;
-}
+import { getWorkerEnv } from "./runtimeEnv.js";
 
 /** D1 catalog binding for the edge read replica, if present in the runtime. */
 export async function readD1(binding: string): Promise<D1Like | undefined> {
   const w = await getWorkerEnv();
   return (w?.[binding] as D1Like | undefined) ?? undefined;
 }
-
-/** R2 bucket binding (e.g. TENANT_ASSETS, PRODUCT_IMAGES), if present. */
-export async function readR2(binding: string): Promise<R2Bucket | undefined> {
-  const w = await getWorkerEnv();
-  return (w?.[binding] as R2Bucket | undefined) ?? undefined;
-}
-
-/**
- * Cloudflare Analytics Engine dataset binding (e.g. ACTIVITY_ANALYTICS), if
- * present. Untyped (`unknown`) deliberately — the caller casts to its own
- * minimal `writeDataPoint` shape (see `activity/store.ts`'s
- * `AnalyticsEngineLike`) rather than this module taking a types dep. Absent in
- * dev/Node and until the binding is provisioned; callers treat undefined as
- * "analytics sink unavailable, skip it" (never an error).
- */
-export async function readAnalytics(binding: string): Promise<unknown | undefined> {
-  const w = await getWorkerEnv();
-  return w?.[binding] ?? undefined;
-}
-
-/**
- * Cloudflare Queue producer binding (e.g. WEBHOOK_DELIVERY_QUEUE), if present.
- * Untyped (`unknown`) deliberately — callers cast to their own minimal
- * queue-shape interface (see `webhooks/cloudflareQueueDispatcher.ts`'s
- * `CloudflareQueueSender`) rather than this module taking a types dep on a
- * specific binding's shape.
- */
-export async function readQueue(binding: string): Promise<unknown | undefined> {
-  const w = await getWorkerEnv();
-  return w?.[binding] ?? undefined;
-}

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

@@ -0,0 +1,198 @@
+/**
+ * Tenant-owned analytics declaration surface (TIER 1).
+ *
+ * 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.
+ */
+import {
+  buildPlatformAdapterDeclaration,
+  ENVIRONMENT_SCHEMA_VERSION,
+  Violations,
+  isPlainObject,
+  rejectUnknownKeys,
+  type BrowserEnvironment,
+  type ContractViolation,
+  type IntegrationDeclarationInput,
+} 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[];
+  /** 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 (discarded) plan resolution. `canonicalHost` is a fixed placeholder, never the
+ * tenant id, so a clone id (which is not a legal hostname) can never fail construction.
+ */
+const CONSTRUCTION_ENVIRONMENT: BrowserEnvironment = {
+  schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+  siteSurface: "storefront",
+  environment: "live",
+  canonicalHost: "tenant-analytics.invalid",
+  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;
+}): TenantAnalyticsMaterialization {
+  const { raw, tenantPublicId } = 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"], v, "");
+  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: CONSTRUCTION_ENVIRONMENT,
+    });
+    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: [] };
+}
+
+/**
+ * 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.
+ */
+export function loadTenantAnalyticsDeclarations(
+  raw: unknown,
+  tenantPublicId: string,
+): readonly IntegrationDeclarationInput[] {
+  return materializeTenantAnalyticsDeclarations({ raw, tenantPublicId }).declarations;
+}

package/apps/storefront/src/lib/monitoring/manifest.ts

@@ -115,7 +115,7 @@ export const MONITORS: readonly Monitor[] = [
     title: "Page / Worker errors (5xx + unhandled exceptions)",
     category: "availability",
     signal: {
-      source: "Cloudflare Worker exceptions + non-2xx responses from middleware/index.ts render path",
+      source: "Cloudflare Worker exceptions + non-2xx responses from the middleware render path",
       observe: "Workers 'Errors' metric + Logpush; alert on error-rate over the request baseline",
     },
     threshold: "5xx rate > 1% over 5m, or any sustained unhandled-exception stream",

package/apps/storefront/src/lib/rawMarketingHtml.ts

@@ -19,6 +19,7 @@ import {
   renderIntegrationPhases,
   INTERACTION_TRACKING_BOOT_JS,
   type EffectivePlan,
+  type ConsentSnapshot,
 } from "@tot/public-runtime";
 import { reportTrackingChainHealth } from "./tracking/interactionHealth.js";
 
@@ -180,6 +181,13 @@ export function rawHtmlResponse(
      * silently omit it. Nonces are stamped per response, never serialized (ADR 0018).
      */
     plan: EffectivePlan;
+    /**
+     * The tenant's actual initial consent snapshot (see Layout.astro's identical
+     * prop). Optional: omitting it falls back to the fail-closed essential-only
+     * default, matching every render path that has not resolved a tenant consent
+     * config (candidate/preview renders).
+     */
+    consentSnapshot?: ConsentSnapshot;
   },
 ): Response {
   let composed =
@@ -222,7 +230,7 @@ export function rawHtmlResponse(
   // per-response nonce placeholder; the middleware substitutes a fresh nonce at serve
   // time (ADR 0018), so the same engine output feeds both mounts identically.
   composed = nonceInlineTags(composed, opts.nonce);
-  const phases = renderIntegrationPhases(opts.plan, opts.nonce);
+  const phases = renderIntegrationPhases(opts.plan, opts.nonce, opts.consentSnapshot);
   composed = injectHeadStart(composed, phases.head);
   composed = injectBodyStart(composed, phases.bodyStart);
   composed = injectBodyEnd(composed, phases.bodyDeferred);