@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/integration/platform-adapters.ts

@@ -0,0 +1,671 @@
+/**
+ * First-class native measurement adapters (ext-admin-04).
+ *
+ * These reviewed measurement destinations are expressed as
+ * PARAMETER-DRIVEN DECLARATIONS over the ONE shared browser-integration contract —
+ * never a per-vendor renderer branch. A merchant enters a public destination id
+ * (a GA4/Ads measurement id, a Meta pixel id) per environment and gets a working,
+ * consent-filtered, CSP-clean measurement integration. Each adapter is:
+ *
+ *   - a {@link PlatformAdapterDefinition} — a Storefront-owned, reviewed template
+ *     that fixes the vendor's exact CSP profile ({@link INTEGRATION_CSP_PROFILES}),
+ *     consent purpose, render phase, performance budget, and semantic-event → vendor
+ *     mapping. The tenant contributes only public config (ids), never code or origins,
+ *     which is why a first-class destination needs no renderer change;
+ *   - built into a tenant-scoped {@link IntegrationDeclarationInput} by
+ *     {@link buildPlatformAdapterDeclaration}, resolved through the SAME pure
+ *     {@link resolveEffectivePlan} every catalog entry uses — so its CSP, consent,
+ *     and lifecycle are the shared ones, and removal is just dropping the declaration
+ *     (planRevision-scoped: no residual markup, events, or CSP);
+ *   - run at the client through {@link createAdapterDestination}, which registers ONE
+ *     stable-id subscription on the platform {@link CommerceEventBroker}. The broker
+ *     owns dedupe (one event per logical action) and consent filtering, so Google and
+ *     Meta each measure a logical page/cart/checkout action exactly once — never a
+ *     duplicate, even with multiple adapters live.
+ *
+ * NON-LIVE SAFETY — by construction, two independent guards:
+ *   1. Destination ids are per-ENVIRONMENT. {@link resolveAdapterDestinationId} returns
+ *      the id for the CURRENT stage only, and {@link buildPlatformAdapterDeclaration}
+ *      REFUSES a config where a non-live stage reuses the live id — so candidate/staged
+ *      traffic can never reach the live property. A stage with no configured id fires
+ *      nothing.
+ *   2. Real conversions fire only on `live`. A conversion-class mapping
+ *      ({@link VendorEventMapping.isConversion}) is dropped on every non-live stage
+ *      ({@link isLiveEnvironment}), so a candidate/staged page never fires a real
+ *      conversion to the vendor, whatever id is configured.
+ *
+ * Public ids only — a GA4 measurement id and a Meta pixel id are public values that
+ * ship in page HTML; neither adapter needs a server-custody secret, so `server`
+ * carries none. If a future first-class destination needs a secret (e.g. a Meta
+ * Conversions API token), it declares it as a server `secretRequirement` NAME and the
+ * value stays in server custody — never in this browser config.
+ */
+import type { ContractResult, ContractViolation } from "./result.js";
+import { Violations, isPlainObject } from "./result.js";
+import type { CommerceEventType, CommerceEvent } from "./events.js";
+import { APPROVED_MARKETING_ACTION_NAMES } from "./events.js";
+import type {
+  CommerceEventBroker,
+  CommerceEventSubscription,
+} from "./commerce-broker.js";
+import type { ConsentPurpose } from "../integration-capabilities.js";
+import {
+  INTEGRATION_ENVIRONMENTS,
+  isLiveEnvironment,
+  type BrowserEnvironment,
+  type IntegrationEnvironment,
+} from "./environment.js";
+import { validateBrowserEnvironment } from "./environment.js";
+import {
+  BROWSER_INTEGRATION_CONTRACT_VERSION,
+  INTEGRATION_MANIFEST_SCHEMA_VERSION,
+} from "./version.js";
+import {
+  validateIntegrationManifest,
+  type IntegrationManifest,
+  type PerformanceBudget,
+} from "./manifest.js";
+import type { IntegrationCspProfile } from "./csp-compiler.js";
+import { INTEGRATION_CSP_PROFILES } from "./csp-compiler.js";
+import { INTEGRATION_CSP_DIRECTIVES } from "./csp.js";
+import { digestValue } from "./digest.js";
+import type { EffectivePlan } from "./plan.js";
+import { resolveEffectivePlan, type IntegrationDeclarationInput } from "./resolve.js";
+
+/** How a single semantic commerce event maps onto a vendor's own event vocabulary. */
+export interface VendorEventMapping {
+  /** The vendor's native event name. */
+  vendorEvent: string;
+  /**
+   * Whether this is a CONVERSION-class signal (checkout/purchase intent). Conversions
+   * are dropped on every non-live stage so they never fire a real conversion.
+   */
+  isConversion: boolean;
+}
+
+/**
+ * A Storefront-owned, reviewed first-class adapter template. It is a DECLARATION over
+ * the shared contract — it fixes the vendor's exact CSP profile, consent purpose,
+ * render phase, budget, and event mapping. The tenant supplies only public ids.
+ */
+export interface PlatformAdapterDefinition {
+  /** Stable adapter id — also the resolved integration `appId`/`ref`. */
+  adapterId: string;
+  /** Merchant-facing destination name. */
+  name: string;
+  /** Plain-language purpose for the inventory row. */
+  purpose: string;
+  publisher: string;
+  supportUrl: string;
+  /** The ONE platform-owned entry module every instance of this adapter points at. */
+  entryAsset: string;
+  /** The curated CSP profile slug this adapter's origins come from. */
+  cspProfile: IntegrationCspProfile;
+  /** The consent purpose the destination depends on (the broker enforces it). */
+  consentPurpose: Exclude<ConsentPurpose, "essential">;
+  /** The vendor-addressable render phase the adapter runs in. */
+  phase: "document.deferred";
+  /** The performance budget the adapter must fit — surfaced in the read model. */
+  performanceBudget: PerformanceBudget;
+  /** Human hint for the public destination-id field (e.g. "GA4 measurement id"). */
+  idLabel: string;
+  /** Validates the shape of a public destination id for this vendor. */
+  validateId(id: string): boolean;
+  /** The semantic commerce events this adapter measures, and their vendor mapping. */
+  eventMap: Readonly<Partial<Record<CommerceEventType, VendorEventMapping>>>;
+}
+
+const GOOGLE_MEASUREMENT_ID = /^G-[A-Z0-9]{4,20}$/;
+const META_PIXEL_ID = /^\d{10,20}$/;
+const AMPLITUDE_PROJECT_KEY = /^(?=[a-f0-9]{32}$)(?=.*[a-f])[a-f0-9]+$/i;
+
+/**
+ * Native Google Analytics 4 measurement. A single public measurement id drives
+ * the platform adapter, which sends reviewed event payloads to the curated analytics
+ * endpoints in the `google-measurement` CSP profile. It does not run a merchant-owned
+ * browser container. Depends on analytics consent (ADR 0023 Q3).
+ */
+export const GOOGLE_MEASUREMENT_ADAPTER: PlatformAdapterDefinition = Object.freeze({
+  adapterId: "platform.google-measurement",
+  name: "Google Analytics 4",
+  purpose: "Native Google Analytics 4 measurement.",
+  publisher: "Storefront platform adapter",
+  supportUrl: "https://developers.google.com/analytics/devguides/collection/ga4",
+  entryAsset: "/platform/google-measurement/v1/entry.mjs",
+  cspProfile: "google-measurement",
+  consentPurpose: "analytics",
+  phase: "document.deferred",
+  performanceBudget: Object.freeze({
+    maxTransferredBytes: 90_000,
+    maxAdditionalRequests: 4,
+    maxMainThreadMilliseconds: 120,
+    mustBeAsyncOrDeferred: true,
+  }),
+  idLabel: "GA4 measurement id (e.g. G-XXXXXXX)",
+  validateId: (id: string) => GOOGLE_MEASUREMENT_ID.test(id),
+  eventMap: Object.freeze({
+    "storefront.page.viewed.v1": { vendorEvent: "page_view", isConversion: false },
+    "storefront.page.viewed.v2": { vendorEvent: "page_view", isConversion: false },
+    "storefront.action.activated.v1": { vendorEvent: "approved_action", isConversion: false },
+  }),
+});
+
+/**
+ * Meta pixel. A single public pixel id drives fbq; the loader is served from
+ * connect.facebook.net and collects to facebook.com (the `meta-pixel` CSP profile).
+ * Depends on marketing consent (advertising attribution).
+ */
+export const META_PIXEL_ADAPTER: PlatformAdapterDefinition = Object.freeze({
+  adapterId: "platform.meta-pixel",
+  name: "Meta pixel",
+  purpose: "Meta (Facebook/Instagram) pixel measurement via fbq.",
+  publisher: "Storefront platform adapter",
+  supportUrl: "https://developers.facebook.com/docs/meta-pixel",
+  entryAsset: "platform/meta-pixel/v1/entry.mjs",
+  cspProfile: "meta-pixel",
+  consentPurpose: "marketing",
+  phase: "document.deferred",
+  performanceBudget: Object.freeze({
+    maxTransferredBytes: 70_000,
+    maxAdditionalRequests: 3,
+    maxMainThreadMilliseconds: 100,
+    mustBeAsyncOrDeferred: true,
+  }),
+  idLabel: "Meta pixel id (15–16 digits)",
+  validateId: (id: string) => META_PIXEL_ID.test(id),
+  eventMap: Object.freeze({
+    "storefront.page.viewed.v1": { vendorEvent: "PageView", isConversion: false },
+    "storefront.product.viewed.v1": { vendorEvent: "ViewContent", isConversion: false },
+    "storefront.cart.item_added.v1": { vendorEvent: "AddToCart", isConversion: false },
+    "storefront.checkout.handoff.v1": { vendorEvent: "InitiateCheckout", isConversion: true },
+  }),
+});
+
+/**
+ * Native Amplitude measurement through the reviewed direct HTTP transport. Only
+ * explicit page views and allowlisted platform action activations are subscribed;
+ * the adapter does not load or configure the Amplitude browser SDK.
+ */
+export const AMPLITUDE_HTTP_ADAPTER: PlatformAdapterDefinition = Object.freeze({
+  adapterId: "platform.amplitude",
+  name: "Amplitude",
+  purpose: "Native Amplitude measurement for explicit page views and approved marketing actions.",
+  publisher: "Storefront platform adapter",
+  supportUrl: "https://amplitude.com/docs/apis/analytics/http-v2",
+  entryAsset: "/platform/amplitude-http/v1/entry.mjs",
+  cspProfile: "amplitude-http",
+  consentPurpose: "analytics",
+  phase: "document.deferred",
+  performanceBudget: Object.freeze({
+    maxTransferredBytes: 8_000,
+    maxAdditionalRequests: 1,
+    maxMainThreadMilliseconds: 10,
+    mustBeAsyncOrDeferred: true,
+  }),
+  idLabel: "Amplitude project API key (32 hexadecimal characters)",
+  validateId: (id: string) => AMPLITUDE_PROJECT_KEY.test(id),
+  eventMap: Object.freeze({
+    "storefront.page.viewed.v1": { vendorEvent: "page_view", isConversion: false },
+    "storefront.page.viewed.v2": { vendorEvent: "page_view", isConversion: false },
+    "storefront.action.activated.v1": { vendorEvent: "marketing_action", isConversion: false },
+  }),
+});
+
+/** The closed set of first-class platform adapters, in catalog order. */
+export const PLATFORM_ADAPTERS: readonly PlatformAdapterDefinition[] = Object.freeze([
+  GOOGLE_MEASUREMENT_ADAPTER,
+  META_PIXEL_ADAPTER,
+  AMPLITUDE_HTTP_ADAPTER,
+]);
+
+const ADAPTERS_BY_ID: ReadonlyMap<string, PlatformAdapterDefinition> = new Map(
+  PLATFORM_ADAPTERS.map((a) => [a.adapterId, a]),
+);
+
+/** Look up a first-class adapter by its stable id, or undefined for an unknown id. */
+export function getPlatformAdapter(adapterId: string): PlatformAdapterDefinition | undefined {
+  return ADAPTERS_BY_ID.get(adapterId);
+}
+
+/** The event types an adapter measures — the subscription scope + the permissions.events set. */
+export function adapterEventTypes(def: PlatformAdapterDefinition): CommerceEventType[] {
+  return Object.keys(def.eventMap) as CommerceEventType[];
+}
+
+// ── Per-environment public destination ids ────────────────────────────────────
+
+/** The public-config key prefix a per-environment destination id is stored under. */
+export const DESTINATION_ID_CONFIG_PREFIX = "destinationId";
+
+/** The flat, primitive public-config key one environment's destination id lives at. */
+export function destinationIdConfigKey(environment: IntegrationEnvironment): string {
+  return `${DESTINATION_ID_CONFIG_PREFIX}_${environment}`;
+}
+
+/** A merchant's per-environment public destination ids. `live` is required to publish. */
+export type DestinationIdsByEnvironment = Partial<Record<IntegrationEnvironment, string>>;
+
+/**
+ * Resolve the destination id that fires for a specific stage from resolved public
+ * config — the current stage's id ONLY. A stage with no configured id returns null,
+ * so nothing fires there; because {@link buildPlatformAdapterDeclaration} refuses a
+ * non-live stage that reuses the live id, this can never return the live id off a
+ * non-live stage. This is the first non-live guard.
+ */
+export function resolveAdapterDestinationId(
+  publicConfig: Record<string, unknown>,
+  environment: IntegrationEnvironment,
+): string | null {
+  const value = publicConfig[destinationIdConfigKey(environment)];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+// ── Declaration builder ───────────────────────────────────────────────────────
+
+/** What the admin surface supplies to configure one first-class adapter. */
+export interface PlatformAdapterConfigInput {
+  adapterId: string;
+  /** Public destination ids per environment. `live` is required; non-live stages take SEPARATE test ids. */
+  ids: DestinationIdsByEnvironment;
+  /** The tenant this adapter is configured for (server-resolved, never browser-set). */
+  tenantPublicId: string;
+  /** The stage this build is resolved against (server-derived; a build is a candidate). */
+  environment: BrowserEnvironment;
+}
+
+/** The consent + budget + destination summary an admin card surfaces in the read model. */
+export interface PlatformAdapterCard {
+  adapterId: string;
+  name: string;
+  purpose: string;
+  publisher: string;
+  supportUrl: string;
+  idLabel: string;
+  /** Consent purposes the destination depends on — visible before publish. */
+  consentPurposes: ConsentPurpose[];
+  /** The performance budget the adapter must fit — visible before publish. */
+  performanceBudget: PerformanceBudget;
+  /** The exact CSP origins this adapter contributes (flattened, sorted). */
+  cspOrigins: string[];
+  /** The semantic events this adapter measures. */
+  eventTypes: CommerceEventType[];
+  /** Which stages have a configured destination id, and whether each is conversion-live. */
+  destinationBehavior: AdapterStageBehavior[];
+}
+
+/** One stage's measurement disposition — makes the non-live safety visible in the read model. */
+export interface AdapterStageBehavior {
+  environment: IntegrationEnvironment;
+  /** True when a destination id is configured for this stage. */
+  configured: boolean;
+  /** True only on `live`: the stage where real conversions fire. */
+  firesRealConversions: boolean;
+}
+
+export type PlatformAdapterBuildResult =
+  | {
+      ok: true;
+      adapterId: string;
+      declaration: IntegrationDeclarationInput;
+      /** Proof the adapter self-serves over the shared resolver with no renderer change. */
+      plan: EffectivePlan;
+      /** The read-model surface: consent purposes + budget + per-stage destination behavior. */
+      card: PlatformAdapterCard;
+    }
+  | { ok: false; reason: "unknown-adapter" | "validation-blocked"; violations: ContractViolation[] };
+
+/** Flatten a curated CSP profile's origins across every directive (sorted, deduped). */
+function profileOrigins(profile: IntegrationCspProfile): string[] {
+  const set = new Set<string>();
+  const sources = INTEGRATION_CSP_PROFILES[profile] ?? {};
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    for (const origin of sources[directive] ?? []) set.add(origin);
+  }
+  return [...set].sort();
+}
+
+/** The per-stage destination behavior, in canonical environment order. */
+function stageBehavior(ids: DestinationIdsByEnvironment): AdapterStageBehavior[] {
+  return INTEGRATION_ENVIRONMENTS.map((environment) => ({
+    environment,
+    configured: typeof ids[environment] === "string" && (ids[environment] as string).length > 0,
+    firesRealConversions: isLiveEnvironment(environment) && typeof ids[environment] === "string",
+  }));
+}
+
+/** Build the read-model card for an adapter definition + a merchant's configured ids. */
+export function buildPlatformAdapterCard(
+  def: PlatformAdapterDefinition,
+  ids: DestinationIdsByEnvironment = {},
+): PlatformAdapterCard {
+  return {
+    adapterId: def.adapterId,
+    name: def.name,
+    purpose: def.purpose,
+    publisher: def.publisher,
+    supportUrl: def.supportUrl,
+    idLabel: def.idLabel,
+    consentPurposes: [def.consentPurpose],
+    performanceBudget: def.performanceBudget,
+    cspOrigins: profileOrigins(def.cspProfile),
+    eventTypes: adapterEventTypes(def),
+    destinationBehavior: stageBehavior(ids),
+  };
+}
+
+/** The catalog of first-class adapters as read-model cards (no tenant ids configured). */
+export function platformAdapterCatalog(): PlatformAdapterCard[] {
+  return PLATFORM_ADAPTERS.map((def) => buildPlatformAdapterCard(def));
+}
+
+/**
+ * Build a tenant-scoped first-class adapter declaration from a merchant's public ids,
+ * fail-closed. An unknown adapter, a missing/invalid live id, an invalid stage id, a
+ * non-live stage that REUSES the live id, or an unresolvable environment yields
+ * violations and NO declaration. The synthesized manifest is resolved into an
+ * effective plan — proof it self-serves over the shared resolver.
+ */
+export function buildPlatformAdapterDeclaration(
+  input: unknown,
+): PlatformAdapterBuildResult {
+  if (!isPlainObject(input)) {
+    return blocked("validation-blocked", [
+      { path: "(root)", code: "type", message: "Adapter config must be an object." },
+    ]);
+  }
+
+  const def = typeof input["adapterId"] === "string" ? getPlatformAdapter(input["adapterId"]) : undefined;
+  if (!def) {
+    return blocked("unknown-adapter", [
+      {
+        path: "adapterId",
+        code: "unknown_adapter",
+        message: `Unknown adapter; first-class adapters are: ${PLATFORM_ADAPTERS.map((a) => a.adapterId).join(", ")}.`,
+      },
+    ]);
+  }
+
+  const v = new Violations();
+
+  const tenantPublicId =
+    typeof input["tenantPublicId"] === "string" && input["tenantPublicId"].length > 0
+      ? input["tenantPublicId"]
+      : undefined;
+  if (tenantPublicId === undefined) {
+    v.add("tenantPublicId", "type", "tenantPublicId must be a non-empty string.");
+  }
+
+  const envResult = validateBrowserEnvironment(input["environment"]);
+  if (!envResult.ok) {
+    for (const violation of envResult.violations) {
+      v.add(violation.path ? `environment.${violation.path}` : "environment", violation.code, violation.message);
+    }
+  }
+
+  const ids = validateDestinationIds(input["ids"], def, v);
+
+  if (!v.ok || tenantPublicId === undefined || ids === undefined || !envResult.ok) {
+    return blocked("validation-blocked", v.items);
+  }
+
+  // Public config: one flat, primitive, PUBLIC id per configured stage. These are
+  // public measurement ids (they ship in page HTML), never secret material.
+  const publicConfig: Record<string, unknown> = {};
+  const schemaProps: Record<string, { type: string }> = {};
+  const requiredKeys: string[] = [];
+  for (const environment of INTEGRATION_ENVIRONMENTS) {
+    const id = ids[environment];
+    if (id === undefined) continue;
+    const key = destinationIdConfigKey(environment);
+    publicConfig[key] = id;
+    schemaProps[key] = { type: "string" };
+    requiredKeys.push(key);
+  }
+
+  const manifest: IntegrationManifest = {
+    schemaVersion: INTEGRATION_MANIFEST_SCHEMA_VERSION,
+    app: {
+      id: def.adapterId,
+      name: def.name,
+      version: "1.0.0",
+      digest: digestValue({ adapterId: def.adapterId, tenantPublicId, publicConfig }),
+      publisher: def.publisher,
+      supportUrl: def.supportUrl,
+    },
+    compatibility: {
+      storefrontBrowserContract: `>=${BROWSER_INTEGRATION_CONTRACT_VERSION}`,
+      configurationSchemaVersion: 1,
+    },
+    browser: {
+      executionTier: "platform-adapter",
+      entry: { asset: def.entryAsset, format: "module", phase: def.phase },
+      contributions: [],
+      dependencies: [],
+      publicConfigSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: requiredKeys.sort(),
+        properties: schemaProps,
+      },
+      consent: {
+        purposes: [def.consentPurpose],
+        loadWhen: "all-declared-purposes-eligible",
+        unknownState: "block",
+      },
+      csp: { profiles: [def.cspProfile], sources: {} },
+      permissions: { events: adapterEventTypes(def), data: [], actions: [], domIntent: "none" },
+      performanceBudget: def.performanceBudget,
+    },
+    // Public ids only — no server-custody secret. A future Conversions-API token would
+    // be declared here as a NAME, never carried in browser config.
+    server: { topics: [], secretRequirements: [] },
+    assurance: { requestedClassification: "baseline", regulatedTenantDefault: "disabled-until-certified" },
+    configurationMigrations: [],
+  };
+
+  const manifestResult = validateIntegrationManifest(manifest);
+  if (!manifestResult.ok) return blocked("validation-blocked", manifestResult.violations);
+
+  const declaration: IntegrationDeclarationInput = {
+    origin: "platform-adapter",
+    ref: def.adapterId,
+    manifest,
+    publicConfig,
+    materializedAssets: [def.entryAsset],
+  };
+
+  const planResult = resolveEffectivePlan({
+    tenantPublicId,
+    environment: envResult.value,
+    declarations: [declaration],
+  });
+  if (!planResult.ok) return blocked("validation-blocked", planResult.violations);
+
+  return {
+    ok: true,
+    adapterId: def.adapterId,
+    declaration,
+    plan: planResult.value,
+    card: buildPlatformAdapterCard(def, ids),
+  };
+}
+
+/**
+ * Validate the per-environment public ids. `live` is required; every provided id must
+ * match the adapter's shape; and NO non-live stage may reuse the live id — that is the
+ * config-time guard that keeps candidate/staged traffic off the live property.
+ */
+function validateDestinationIds(
+  value: unknown,
+  def: PlatformAdapterDefinition,
+  v: Violations,
+): DestinationIdsByEnvironment | undefined {
+  if (!isPlainObject(value)) {
+    v.add("ids", "type", "ids must be an object of { environment: destinationId }.");
+    return undefined;
+  }
+
+  const out: DestinationIdsByEnvironment = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (!(INTEGRATION_ENVIRONMENTS as readonly string[]).includes(key)) {
+      v.add(`ids.${key}`, "unknown_enum", `Unknown environment "${key}"; one of: ${INTEGRATION_ENVIRONMENTS.join(", ")}.`);
+      continue;
+    }
+    if (typeof raw !== "string" || raw.length === 0) {
+      v.add(`ids.${key}`, "type", "A destination id must be a non-empty string.");
+      continue;
+    }
+    if (!def.validateId(raw)) {
+      v.add(`ids.${key}`, "format", `"${raw}" is not a valid ${def.idLabel}.`);
+      continue;
+    }
+    out[key as IntegrationEnvironment] = raw;
+  }
+
+  const liveId = out["live"];
+  if (liveId === undefined) {
+    v.add("ids.live", "required", "A live destination id is required to publish this adapter.");
+  } else {
+    for (const environment of INTEGRATION_ENVIRONMENTS) {
+      if (environment === "live") continue;
+      if (out[environment] === liveId) {
+        v.add(
+          `ids.${environment}`,
+          "non_live_reuses_live_id",
+          `The "${environment}" stage reuses the live destination id; non-live traffic must never reach the live property. Use a separate test id or leave it unset.`,
+        );
+      }
+    }
+  }
+
+  return v.ok ? out : undefined;
+}
+
+function blocked(
+  reason: "unknown-adapter" | "validation-blocked",
+  violations: ContractViolation[],
+): PlatformAdapterBuildResult {
+  return { ok: false, reason, violations };
+}
+
+// ── Client runtime: the broker subscription each adapter registers ─────────────
+
+/** One mapped vendor call the adapter's entry module makes. */
+export interface VendorCall {
+  adapterId: string;
+  /** The public destination id for the CURRENT stage this call targets. */
+  destinationId: string;
+  /** The vendor's own event name. */
+  vendorEvent: string;
+  /** The semantic event this maps from. */
+  eventType: CommerceEventType;
+  /** The logical event id — the same id the broker deduped on. */
+  logicalId: string;
+  /** The anonymous, allowlisted payload (already validated by the broker). */
+  data: Record<string, unknown>;
+  /** Whether this was a conversion-class signal (only ever true on `live`). */
+  isConversion: boolean;
+}
+
+/** The vendor sink the entry module injects, or a test spy. */
+export type AdapterDispatch = (call: VendorCall) => void;
+
+export interface CreateAdapterDestinationInput {
+  adapter: PlatformAdapterDefinition;
+  /** The resolved per-integration public config (holds the per-stage destination ids). */
+  publicConfig: Record<string, unknown>;
+  /** The resolved environment — its stage decides which id fires and whether conversions fire. */
+  environment: BrowserEnvironment;
+  /** The vendor sink. Injected so the adapter runtime is pure and node-testable. */
+  dispatch: AdapterDispatch;
+}
+
+/**
+ * Build the ONE broker subscription an adapter's entry module registers. Its `id` is
+ * the stable adapter id, so a re-subscribe (after a consent/config change) REPLACES
+ * rather than stacks — a logical action still measures exactly once. The broker fans
+ * each logical action to this subscriber exactly once and only when the adapter's
+ * consent purpose is eligible, so consent filtering and one-per-action dedupe are the
+ * broker's, shared with every other destination.
+ *
+ * The handler is the non-live enforcement point: it fires only to the CURRENT stage's
+ * destination id (never the live id off a non-live stage), and drops conversion-class
+ * events on every non-live stage — so a candidate/staged page never fires a real
+ * conversion.
+ */
+export function createAdapterDestination(
+  input: CreateAdapterDestinationInput,
+): CommerceEventSubscription {
+  const { adapter, publicConfig, environment, dispatch } = input;
+  return {
+    id: adapter.adapterId,
+    consentPurpose: adapter.consentPurpose,
+    types: adapterEventTypes(adapter),
+    sink: {
+      kind: "callback",
+      handler: (event: CommerceEvent) => {
+        const call = mapCommerceEventToVendorCall(adapter, publicConfig, environment, event);
+        if (call) dispatch(call);
+      },
+    },
+  };
+}
+
+/**
+ * Map one delivered commerce event to a vendor call, applying both non-live guards.
+ * Returns null (no vendor call) when: the current stage has no destination id; the
+ * event type is not in the adapter's map; or the mapping is a conversion on a non-live
+ * stage. Pure — exported so the mapping + non-live gating are directly testable.
+ */
+export function mapCommerceEventToVendorCall(
+  adapter: PlatformAdapterDefinition,
+  publicConfig: Record<string, unknown>,
+  environment: BrowserEnvironment,
+  event: CommerceEvent,
+): VendorCall | null {
+  const destinationId = resolveAdapterDestinationId(publicConfig, environment.environment);
+  if (!destinationId) return null;
+
+  const mapping = adapter.eventMap[event.type];
+  if (!mapping) return null;
+
+  let vendorEvent = mapping.vendorEvent;
+  if (
+    adapter.adapterId === GOOGLE_MEASUREMENT_ADAPTER.adapterId &&
+    event.type === "storefront.action.activated.v1"
+  ) {
+    const name = event.data["name"];
+    if (
+      typeof name !== "string" ||
+      !(APPROVED_MARKETING_ACTION_NAMES as readonly string[]).includes(name)
+    ) return null;
+    vendorEvent = name;
+  }
+
+  // Guard 2: real conversions fire only on live. A non-live stage never fires a real
+  // conversion, even to a configured test id.
+  if (mapping.isConversion && !isLiveEnvironment(environment.environment)) return null;
+
+  return {
+    adapterId: adapter.adapterId,
+    destinationId,
+    vendorEvent,
+    eventType: event.type,
+    logicalId: event.id,
+    data: event.data,
+    isConversion: mapping.isConversion,
+  };
+}
+
+/**
+ * Register a first-class adapter's destination on the platform commerce broker and
+ * return the unsubscribe handle. Removing the adapter (unsubscribe) withdraws its
+ * measurement with no residue — the mirror of dropping the declaration from the plan,
+ * which withdraws its CSP + entry module.
+ */
+export function registerAdapterDestination(
+  broker: CommerceEventBroker,
+  input: CreateAdapterDestinationInput,
+): () => void {
+  return broker.subscribe(createAdapterDestination(input));
+}