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

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

@@ -0,0 +1,701 @@
+/**
+ * The canonical semantic commerce event contract — the shared spine for dual
+ * client/server measurement (ADR 0014 M3 `integration-events-dual-delivery`,
+ * M2 `integration-commerce-data-minimized`, M1 `integration-checkout-provider-specific`).
+ *
+ * One contract feeds two delivery channels. Every event is a CloudEvents 1.0
+ * envelope with a small server-owned storefront extension:
+ *
+ *   - The envelope is SEMANTIC and VERSIONED (`storefront.<domain>.<action>.vN`),
+ *     never DOM-selector based. Unknown or unreleased types fail closed.
+ *   - `id` is the OPAQUE LOGICAL EVENT IDENTITY: the same logical action delivered
+ *     to both a browser destination and a server destination carries one `id`, so
+ *     downstream vendors deduplicate on it (`eventDedupeKey`). Replays and late
+ *     duplicates collapse to that key.
+ *   - `correlation.id` is the attribution THREAD that spans a browser
+ *     `checkout.handoff` and the later server-authoritative `order.*` — distinct
+ *     logical events, one bounded-lifetime correlation.
+ *   - `storefront.tenant`, `storefront.environment`, and `storefront.siteSurface`
+ *     are SERVER-OWNED: stamped from trusted execution context, never read from a
+ *     caller-supplied payload. `validateCommerceEventInContext` rejects any event
+ *     whose claimed tenant/environment/surface disagrees with the trusted context,
+ *     so tenant/env cannot be caller-forged.
+ *   - `storefront.emitter` names the delivery channel of THIS instance. A
+ *     verified-provider (server-authoritative) event type — `order.created`,
+ *     `order.fulfilled` — cannot be emitted by the browser: a browser-emitted
+ *     conversion is rejected (`forged_authority`), so generic browser code cannot
+ *     invent a purchase.
+ *   - Payloads are anonymous and field-allowlisted per event type: no customer
+ *     identity, address, payment data, identity result, preview token, signed-cart
+ *     material, or nonce. Data keys outside a type's catalog are rejected.
+ *
+ * The per-field owner/purpose/sensitivity catalog and retention classes live in
+ * `./events-catalog.ts`; the human-readable contract is
+ * `docs/architecture/commerce-event-contract.md`. The reserved completed-
+ * navigation event (charter invariant 9) shares the same envelope roots and ships
+ * before any client router.
+ */
+import type { ContractResult } from "./result.js";
+import {
+  Violations,
+  reqObject,
+  childObject,
+  reqEnum,
+  reqLiteral,
+  reqString,
+  reqInt,
+  reqStringArray,
+  reqIsoTimestamp,
+  rejectUnknownKeys,
+  joinPath,
+} from "./result.js";
+import {
+  COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION,
+  CONSENT_SNAPSHOT_SCHEMA_VERSION,
+} from "./version.js";
+import { INTEGRATION_ENVIRONMENTS, INTEGRATION_SITE_SURFACES } from "./environment.js";
+import type { IntegrationEnvironment, IntegrationSiteSurface } from "./environment.js";
+import { findForbiddenFields } from "./secrets.js";
+import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+
+/**
+ * The reserved commerce event taxonomy. Every accepted type is here; an unknown
+ * type fails closed (`unknown_enum`). New behavior is a NEW `.vN` type or a new
+ * name — a type is never silently reinterpreted.
+ */
+export const COMMERCE_EVENT_TYPES = [
+  "storefront.page.viewed.v1",
+  "storefront.page.viewed.v2",
+  "storefront.action.activated.v1",
+  "storefront.product.viewed.v1",
+  "storefront.cart.item_added.v1",
+  "storefront.cart.item_removed.v1",
+  "storefront.cart.updated.v1",
+  "storefront.checkout.handoff.v1",
+  "storefront.purchase.completed.v1",
+  "storefront.consent.changed.v1",
+  "storefront.order.created.v1",
+  "storefront.order.fulfilled.v1",
+] as const;
+export type CommerceEventType = (typeof COMMERCE_EVENT_TYPES)[number];
+
+/**
+ * The browser-deliverable, consent-gated post-purchase signal a sandboxed
+ * third-party subscriber reacts to (post-purchase NPS / review / loyalty /
+ * referral widgets). It is NOT the authoritative verified order —
+ * `storefront.order.created.v1` / `.fulfilled.v1` stay `verified-provider` and are
+ * broker-refused for the browser (`forged_authority`), and the financial record
+ * lives only on the server. This is an ANONYMOUS, minimized (M2), analytics-gated
+ * signal that *a purchase completed*, carrying no order id, customer identity,
+ * payment data, or signed-cart material — safe to fan out to a browser subscriber
+ * under analytics consent.
+ */
+export const PURCHASE_COMPLETED_EVENT_TYPE = "storefront.purchase.completed.v1" as const;
+
+/**
+ * Forward-declared types whose NAMES are reserved but whose semantics are not yet
+ * stable. They require provider truth (M1) before they can be emitted, so an
+ * instance of one is rejected `reserved_unavailable` rather than silently
+ * accepted or confused with an unknown name.
+ */
+export const FORWARD_DECLARED_COMMERCE_EVENT_TYPES = [
+  "storefront.order.cancelled.v1",
+  "storefront.order.refunded.v1",
+  "storefront.checkout.completed.v1",
+] as const;
+export type ForwardDeclaredCommerceEventType =
+  (typeof FORWARD_DECLARED_COMMERCE_EVENT_TYPES)[number];
+
+/** The reserved completed-navigation event that must ship before any client router. */
+export const NAVIGATION_COMPLETED_EVENT_TYPE = "storefront.navigation.completed.v1" as const;
+
+export const NAVIGATION_KINDS = ["document", "hash", "back-forward", "redirect"] as const;
+export type NavigationKind = (typeof NAVIGATION_KINDS)[number];
+
+/** Stable semantic marketing-action namespace; action labels and DOM bindings never qualify. */
+export const MARKETING_ACTION_NAME_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*_mktg$/;
+
+/** The program-approved v1 marketing action identifiers. */
+export const APPROVED_MARKETING_ACTION_NAMES = [
+  "user_clicked_contact_sales_mktg",
+  "user_clicked_create_account_mktg",
+  "user_clicked_login_mktg",
+  "user_clicked_contact_support_consumer_mktg",
+  "user_clicked_contact_support_partner_mktg",
+] as const;
+export type ApprovedMarketingActionName = (typeof APPROVED_MARKETING_ACTION_NAMES)[number];
+
+/**
+ * Which channel is AUTHORITATIVE for a given event type. `browser` events
+ * originate in the document (a server destination is a mirror). `verified-provider`
+ * events are authored only from a verified provider webhook and can never be
+ * emitted by the browser.
+ */
+export type EventSourceOfTruth = "browser" | "verified-provider";
+export const EVENT_SOURCE_OF_TRUTH: Record<CommerceEventType, EventSourceOfTruth> = {
+  "storefront.page.viewed.v1": "browser",
+  "storefront.page.viewed.v2": "browser",
+  "storefront.action.activated.v1": "browser",
+  "storefront.product.viewed.v1": "browser",
+  "storefront.cart.item_added.v1": "browser",
+  "storefront.cart.item_removed.v1": "browser",
+  "storefront.cart.updated.v1": "browser",
+  "storefront.checkout.handoff.v1": "browser",
+  "storefront.purchase.completed.v1": "browser",
+  "storefront.consent.changed.v1": "browser",
+  "storefront.order.created.v1": "verified-provider",
+  "storefront.order.fulfilled.v1": "verified-provider",
+};
+
+/**
+ * Whether a released type can be delivered to a browser subscriber — its
+ * source of truth is the browser. A `verified-provider` type (a conversion) is
+ * never browser-deliverable: the broker refuses to emit it (`forged_authority`)
+ * and no browser path carries it to a sandbox subscriber. This is the check a
+ * subscription-wiring layer runs over a manifest's declared `permissions.events`
+ * before it wires a delivery, so an impossible (verified-provider), unknown, or
+ * forward-declared event is rejected rather than silently never firing.
+ */
+export function isBrowserDeliverableEventType(type: string): type is CommerceEventType {
+  return (
+    (COMMERCE_EVENT_TYPES as readonly string[]).includes(type) &&
+    EVENT_SOURCE_OF_TRUTH[type as CommerceEventType] === "browser"
+  );
+}
+
+/** The delivery channel that emitted a specific envelope instance. */
+export const EVENT_EMITTERS = ["browser", "server"] as const;
+export type EventEmitter = (typeof EVENT_EMITTERS)[number];
+
+/**
+ * The server-owned identity block. `tenant`, `environment`, and `siteSurface` are
+ * stamped from trusted execution context (the renderer for a browser emitter, the
+ * verified webhook receiver for a server emitter) — never from caller input.
+ * `sequence` is an optional per-emitter monotonic counter for out-of-order
+ * detection independent of wall-clock `time`.
+ */
+export interface CommerceEventContext {
+  schemaVersion: typeof COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION;
+  tenant: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+  emitter: EventEmitter;
+  sequence?: number;
+}
+
+/** The base storefront context the navigation lifecycle event carries. */
+export interface StorefrontEventContext {
+  schemaVersion: typeof COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+}
+
+/** The consent snapshot a browser event was filtered against (a reference, not raw consent state). */
+export interface EventConsentSnapshot {
+  schemaVersion: typeof CONSENT_SNAPSHOT_SCHEMA_VERSION;
+  snapshotId: string;
+  eligiblePurposes: string[];
+}
+
+/** The bounded-lifetime attribution thread that spans handoff and verified order events. */
+export interface EventCorrelation {
+  id: string;
+  expiresAt: string;
+}
+
+export interface CommerceEvent {
+  specversion: "1.0";
+  id: string;
+  source: string;
+  type: CommerceEventType;
+  subject: string;
+  time: string;
+  datacontenttype: "application/json";
+  dataschema?: string;
+  storefront: CommerceEventContext;
+  correlation: EventCorrelation;
+  consent: EventConsentSnapshot;
+  data: Record<string, unknown>;
+}
+
+export interface NavigationCompletedEvent {
+  specversion: "1.0";
+  id: string;
+  source: string;
+  type: typeof NAVIGATION_COMPLETED_EVENT_TYPE;
+  time: string;
+  storefront: StorefrontEventContext;
+  data: { from: string; to: string; kind: NavigationKind };
+}
+
+/** The trusted execution context a submitted event's server-owned fields must match. */
+export interface TrustedEventContext {
+  tenant: string;
+  environment: IntegrationEnvironment;
+  siteSurface: IntegrationSiteSurface;
+}
+
+/**
+ * The one canonical dedupe/idempotency key for a logical event: its `id`. Both the
+ * browser and the server delivery of a single logical action carry the same `id`,
+ * so a consumer that keys on this value processes each logical event exactly once
+ * regardless of channel, retry, or replay.
+ */
+export function eventDedupeKey(event: Pick<CommerceEvent, "id">): string {
+  return event.id;
+}
+
+/** Allowed data keys per event type. Data is CLOSED: an unlisted key is rejected. */
+export const COMMERCE_EVENT_DATA_FIELDS: Record<CommerceEventType, readonly string[]> = {
+  "storefront.page.viewed.v1": ["path", "title"],
+  "storefront.page.viewed.v2": ["path", "attribution"],
+  "storefront.action.activated.v1": ["name"],
+  "storefront.product.viewed.v1": ["productId", "variantId", "listId", "position", "currency", "unitPrice"],
+  "storefront.cart.item_added.v1": ["productId", "variantId", "quantity", "unitPrice", "currency"],
+  "storefront.cart.item_removed.v1": ["productId", "variantId", "quantity", "unitPrice", "currency"],
+  "storefront.cart.updated.v1": ["currency", "value", "itemCount", "items"],
+  "storefront.checkout.handoff.v1": ["currency", "value", "itemCount", "items"],
+  "storefront.purchase.completed.v1": ["currency", "value", "itemCount", "items"],
+  "storefront.consent.changed.v1": ["eligiblePurposes", "previousPurposes"],
+  "storefront.order.created.v1": ["orderId", "currency", "value", "itemCount", "items"],
+  "storefront.order.fulfilled.v1": ["orderId", "currency", "value", "itemCount", "items"],
+};
+
+/** Allowed keys on a line item within a cart/handoff/order `items[]` array. */
+export const COMMERCE_EVENT_LINE_ITEM_FIELDS = [
+  "productId",
+  "variantId",
+  "quantity",
+  "unitPrice",
+] as const;
+
+/** Key tokens that would carry customer identity or payment data (ADR 0014 M2). */
+const PII_TOKENS = new Set([
+  "email",
+  "phone",
+  "name",
+  "firstname",
+  "lastname",
+  "address",
+  "dob",
+  "birthdate",
+  "ssn",
+  "card",
+  "cardnumber",
+  "pan",
+  "cvv",
+  "cvc",
+  "payment",
+]);
+
+/** A non-negative decimal money string, e.g. `"42.50"` — never a float, never a locale form. */
+const DECIMAL_STRING = /^\d+(\.\d+)?$/;
+
+function findPiiFields(value: unknown, path: string, out: { path: string; code: string; message: string }[]): void {
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => findPiiFields(item, `${path}[${i}]`, out));
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    const collapsed = key.replace(/[_\-.]/g, "").toLowerCase();
+    // action.activated's data.name is a constrained *_mktg registry identifier,
+    // not a person's name. Its type-specific validator enforces that closed syntax.
+    const semanticActionName = path === "data" && key === "name";
+    if (PII_TOKENS.has(collapsed) && !semanticActionName) {
+      out.push({
+        path: joinPath(path, key),
+        code: "pii_field",
+        message: `Field "${key}" looks like customer PII/payment data; browser events must be anonymous and minimal.`,
+      });
+    }
+    findPiiFields(child, joinPath(path, key), out);
+  }
+}
+
+function reqDecimalString(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): void {
+  const value = reqString(obj, key, v, path);
+  if (value !== undefined && !DECIMAL_STRING.test(value)) {
+    v.add(joinPath(path, key), "format", `"${key}" must be a non-negative decimal string, e.g. "42.50".`);
+  }
+}
+
+function validateLineItems(parent: Record<string, unknown>, v: Violations, path: string): void {
+  const items = parent["items"];
+  if (!Array.isArray(items)) {
+    v.add(joinPath(path, "items"), "type", "Expected an array at \"items\".");
+    return;
+  }
+  items.forEach((raw, i) => {
+    const itemPath = `${joinPath(path, "items")}[${i}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      v.add(itemPath, "type", "Expected an object.");
+      return;
+    }
+    const item = raw as Record<string, unknown>;
+    rejectUnknownKeys(item, COMMERCE_EVENT_LINE_ITEM_FIELDS, v, itemPath);
+    reqString(item, "productId", v, itemPath);
+    if ("variantId" in item) reqString(item, "variantId", v, itemPath);
+    reqInt(item, "quantity", v, itemPath);
+    reqDecimalString(item, "unitPrice", v, itemPath);
+  });
+}
+
+const UTM_FIELDS = ["source", "medium", "campaign", "term", "content"] as const;
+const SAFE_UTM_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+const PROTECTED_ATTRIBUTION_VALUE =
+  /(?:@|\d{7,}|(?:^|[._~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[._~-]))/i;
+
+function validatePageAttribution(parent: Record<string, unknown>, v: Violations): void {
+  const attribution = childObject(parent, "attribution", v, "data");
+  if (!attribution) return;
+  rejectUnknownKeys(attribution, ["referrer", "utm"], v, "data.attribution");
+  if (!("referrer" in attribution) && !("utm" in attribution)) {
+    v.add("data.attribution", "empty", "Attribution must contain a minimized referrer or UTM object.");
+  }
+
+  if ("referrer" in attribution) {
+    const referrer = childObject(attribution, "referrer", v, "data.attribution");
+    if (referrer) {
+      rejectUnknownKeys(referrer, ["origin"], v, "data.attribution.referrer");
+      const origin = reqString(referrer, "origin", v, "data.attribution.referrer");
+      if (origin !== undefined) {
+        try {
+          const url = new URL(origin);
+          if (
+            !["http:", "https:"].includes(url.protocol) ||
+            url.origin !== origin ||
+            url.username !== "" ||
+            url.password !== ""
+          ) {
+            v.add(
+              "data.attribution.referrer.origin",
+              "format",
+              "Referrer must be an http(s) origin only; paths, query strings, fragments, and credentials are forbidden.",
+            );
+          }
+        } catch {
+          v.add("data.attribution.referrer.origin", "format", "Referrer must be a valid http(s) origin.");
+        }
+      }
+    }
+  }
+
+  if ("utm" in attribution) {
+    const utm = childObject(attribution, "utm", v, "data.attribution");
+    if (utm) {
+      rejectUnknownKeys(utm, UTM_FIELDS, v, "data.attribution.utm");
+      if (Object.keys(utm).length === 0) {
+        v.add("data.attribution.utm", "empty", "UTM must contain at least one allowlisted field.");
+      }
+      for (const key of UTM_FIELDS) {
+        if (!(key in utm)) continue;
+        const value = reqString(utm, key, v, "data.attribution.utm");
+        if (value !== undefined && !SAFE_UTM_VALUE.test(value)) {
+          v.add(
+            `data.attribution.utm.${key}`,
+            "format",
+            `UTM ${key} must be a 1-128 character opaque campaign token.`,
+          );
+        }
+        if (value !== undefined && PROTECTED_ATTRIBUTION_VALUE.test(value)) {
+          v.add(
+            `data.attribution.utm.${key}`,
+            "protected_value",
+            `UTM ${key} resembles PII or protected material and must not be emitted.`,
+          );
+        }
+      }
+    }
+  }
+}
+
+/** Validate a type's `data` against its closed field catalog. */
+function validateEventData(
+  type: CommerceEventType,
+  data: Record<string, unknown>,
+  v: Violations,
+): void {
+  rejectUnknownKeys(data, COMMERCE_EVENT_DATA_FIELDS[type], v, "data");
+  switch (type) {
+    case "storefront.page.viewed.v1":
+      reqString(data, "path", v, "data");
+      if ("title" in data) reqString(data, "title", v, "data");
+      break;
+    case "storefront.page.viewed.v2":
+      {
+        const path = reqString(data, "path", v, "data");
+        if (
+          path !== undefined &&
+          (!path.startsWith("/") ||
+            path.startsWith("//") ||
+            path.includes("\\") ||
+            path.includes("?") ||
+            path.includes("#"))
+        ) {
+          v.add(
+            "data.path",
+            "format",
+            "Page path must be a root-relative local path and exclude network-path forms, backslashes, query strings, and fragments.",
+          );
+        }
+        if (resemblesManagedAnalyticsPii(path)) {
+          v.add(
+            "data.path",
+            "pii_value",
+            "Page paths cannot contain values resembling customer PII.",
+          );
+        }
+      }
+      if ("attribution" in data) validatePageAttribution(data, v);
+      break;
+    case "storefront.action.activated.v1": {
+      const name = reqString(data, "name", v, "data");
+      if (name !== undefined && !MARKETING_ACTION_NAME_PATTERN.test(name)) {
+        v.add("data.name", "format", "Action name must be lowercase snake_case and end in _mktg.");
+      } else if (
+        name !== undefined &&
+        !(APPROVED_MARKETING_ACTION_NAMES as readonly string[]).includes(name)
+      ) {
+        v.add("data.name", "unknown_enum", "Action name is not in the approved v1 marketing action allowlist.");
+      }
+      break;
+    }
+    case "storefront.product.viewed.v1":
+      reqString(data, "productId", v, "data");
+      if ("variantId" in data) reqString(data, "variantId", v, "data");
+      if ("listId" in data) reqString(data, "listId", v, "data");
+      if ("position" in data) reqInt(data, "position", v, "data");
+      if ("currency" in data) reqString(data, "currency", v, "data");
+      if ("unitPrice" in data) reqDecimalString(data, "unitPrice", v, "data");
+      break;
+    case "storefront.cart.item_added.v1":
+    case "storefront.cart.item_removed.v1":
+      reqString(data, "productId", v, "data");
+      if ("variantId" in data) reqString(data, "variantId", v, "data");
+      reqInt(data, "quantity", v, "data");
+      if ("unitPrice" in data) reqDecimalString(data, "unitPrice", v, "data");
+      if ("currency" in data) reqString(data, "currency", v, "data");
+      break;
+    case "storefront.cart.updated.v1":
+    case "storefront.checkout.handoff.v1":
+    case "storefront.purchase.completed.v1":
+      reqString(data, "currency", v, "data");
+      reqDecimalString(data, "value", v, "data");
+      reqInt(data, "itemCount", v, "data");
+      validateLineItems(data, v, "data");
+      break;
+    case "storefront.consent.changed.v1":
+      reqStringArray(data, "eligiblePurposes", v, "data");
+      if ("previousPurposes" in data) reqStringArray(data, "previousPurposes", v, "data");
+      break;
+    case "storefront.order.created.v1":
+    case "storefront.order.fulfilled.v1":
+      reqString(data, "orderId", v, "data");
+      reqString(data, "currency", v, "data");
+      reqDecimalString(data, "value", v, "data");
+      reqInt(data, "itemCount", v, "data");
+      validateLineItems(data, v, "data");
+      break;
+  }
+}
+
+function validateCommerceContext(
+  parent: Record<string, unknown>,
+  type: CommerceEventType | undefined,
+  v: Violations,
+): void {
+  const ctx = childObject(parent, "storefront", v, "");
+  if (!ctx) return;
+  rejectUnknownKeys(
+    ctx,
+    ["schemaVersion", "tenant", "environment", "siteSurface", "emitter", "sequence"],
+    v,
+    "storefront",
+  );
+  reqLiteral(ctx, "schemaVersion", COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION, v, "storefront");
+  reqString(ctx, "tenant", v, "storefront");
+  reqEnum(ctx, "environment", INTEGRATION_ENVIRONMENTS, v, "storefront");
+  reqEnum(ctx, "siteSurface", INTEGRATION_SITE_SURFACES, v, "storefront");
+  const emitter = reqEnum(ctx, "emitter", EVENT_EMITTERS, v, "storefront");
+  if ("sequence" in ctx) reqInt(ctx, "sequence", v, "storefront");
+
+  // No-forge of authority: a verified-provider event type can only be emitted by
+  // the server. A browser-emitted conversion is rejected, not trusted.
+  if (type && emitter === "browser" && EVENT_SOURCE_OF_TRUTH[type] === "verified-provider") {
+    v.add(
+      "storefront.emitter",
+      "forged_authority",
+      `"${type}" is server-authoritative (verified provider); a browser emitter cannot author it.`,
+    );
+  }
+}
+
+function validateBaseStorefrontContext(parent: Record<string, unknown>, v: Violations): void {
+  const ctx = childObject(parent, "storefront", v, "");
+  if (!ctx) return;
+  rejectUnknownKeys(ctx, ["schemaVersion", "environment", "siteSurface"], v, "storefront");
+  reqLiteral(ctx, "schemaVersion", COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION, v, "storefront");
+  reqEnum(ctx, "environment", INTEGRATION_ENVIRONMENTS, v, "storefront");
+  reqEnum(ctx, "siteSurface", INTEGRATION_SITE_SURFACES, v, "storefront");
+}
+
+export function validateCommerceEvent(input: unknown): ContractResult<CommerceEvent> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+
+  rejectUnknownKeys(
+    obj,
+    [
+      "specversion",
+      "id",
+      "source",
+      "type",
+      "subject",
+      "time",
+      "datacontenttype",
+      "dataschema",
+      "storefront",
+      "correlation",
+      "consent",
+      "data",
+    ],
+    v,
+    "",
+  );
+
+  reqLiteral(obj, "specversion", "1.0", v, "");
+  const id = reqString(obj, "id", v, "");
+  if (resemblesManagedAnalyticsPii(id)) {
+    v.add("id", "pii_value", "Event ids must be opaque and cannot resemble customer PII.");
+  }
+  reqString(obj, "source", v, "");
+
+  // Type resolution fails closed: a reserved-but-unreleased forward declaration is
+  // rejected distinctly from an entirely unknown name, and only a released type
+  // resolves to a concrete `data` schema.
+  const rawType = obj["type"];
+  let type: CommerceEventType | undefined;
+  if (
+    typeof rawType === "string" &&
+    (FORWARD_DECLARED_COMMERCE_EVENT_TYPES as readonly string[]).includes(rawType)
+  ) {
+    v.add(
+      "type",
+      "reserved_unavailable",
+      `"${rawType}" is reserved but not yet available; it requires verified provider truth and stable semantics.`,
+    );
+  } else {
+    type = reqEnum(obj, "type", COMMERCE_EVENT_TYPES, v, "");
+  }
+
+  reqString(obj, "subject", v, "");
+  reqIsoTimestamp(obj, "time", v, "");
+  reqLiteral(obj, "datacontenttype", "application/json", v, "");
+  if ("dataschema" in obj) reqString(obj, "dataschema", v, "");
+
+  validateCommerceContext(obj, type, v);
+
+  const correlation = childObject(obj, "correlation", v, "");
+  if (correlation) {
+    rejectUnknownKeys(correlation, ["id", "expiresAt"], v, "correlation");
+    const correlationId = reqString(correlation, "id", v, "correlation");
+    if (resemblesManagedAnalyticsPii(correlationId)) {
+      v.add(
+        "correlation.id",
+        "pii_value",
+        "Correlation ids must be opaque and cannot resemble customer PII.",
+      );
+    }
+    reqIsoTimestamp(correlation, "expiresAt", v, "correlation");
+  }
+
+  const consent = childObject(obj, "consent", v, "");
+  if (consent) {
+    rejectUnknownKeys(consent, ["schemaVersion", "snapshotId", "eligiblePurposes"], v, "consent");
+    reqLiteral(consent, "schemaVersion", CONSENT_SNAPSHOT_SCHEMA_VERSION, v, "consent");
+    reqString(consent, "snapshotId", v, "consent");
+    reqStringArray(consent, "eligiblePurposes", v, "consent");
+  }
+
+  const data = childObject(obj, "data", v, "");
+  if (data) {
+    if (type) validateEventData(type, data, v);
+    findPiiFields(data, "data", v.items);
+  }
+
+  for (const violation of findForbiddenFields(obj)) v.items.push(violation);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return { ok: true, value: input as CommerceEvent };
+}
+
+/**
+ * Validate a submitted event AND prove its server-owned fields were not forged.
+ * `trusted` is the tenant/environment/surface the server already knows for the
+ * execution context that produced the event; any disagreement is a
+ * `context_mismatch` violation, so a caller cannot assert a different tenant or a
+ * more-privileged environment than the one it is actually running in.
+ */
+export function validateCommerceEventInContext(
+  input: unknown,
+  trusted: TrustedEventContext,
+): ContractResult<CommerceEvent> {
+  const base = validateCommerceEvent(input);
+  if (!base.ok) return base;
+  const v = new Violations();
+  const ctx = base.value.storefront;
+  if (ctx.tenant !== trusted.tenant) {
+    v.add("storefront.tenant", "context_mismatch", "tenant is server-owned and must match the trusted execution context.");
+  }
+  if (ctx.environment !== trusted.environment) {
+    v.add("storefront.environment", "context_mismatch", "environment is server-owned and must match the trusted execution context.");
+  }
+  if (ctx.siteSurface !== trusted.siteSurface) {
+    v.add("storefront.siteSurface", "context_mismatch", "siteSurface is server-owned and must match the trusted execution context.");
+  }
+  if (!v.ok) return { ok: false, violations: v.items };
+  return base;
+}
+
+export function validateNavigationCompletedEvent(
+  input: unknown,
+): ContractResult<NavigationCompletedEvent> {
+  const v = new Violations();
+  const obj = reqObject(input, v, "");
+  if (!obj) return { ok: false, violations: v.items };
+
+  rejectUnknownKeys(
+    obj,
+    ["specversion", "id", "source", "type", "time", "storefront", "data"],
+    v,
+    "",
+  );
+
+  reqLiteral(obj, "specversion", "1.0", v, "");
+  reqString(obj, "id", v, "");
+  reqString(obj, "source", v, "");
+  reqLiteral(obj, "type", NAVIGATION_COMPLETED_EVENT_TYPE, v, "");
+  reqIsoTimestamp(obj, "time", v, "");
+  validateBaseStorefrontContext(obj, v);
+
+  const data = childObject(obj, "data", v, "");
+  if (data) {
+    rejectUnknownKeys(data, ["from", "to", "kind"], v, "data");
+    reqString(data, "from", v, "data");
+    reqString(data, "to", v, "data");
+    reqEnum(data, "kind", NAVIGATION_KINDS, v, "data");
+  }
+
+  // Payloads exclude candidate wrappers/tokens.
+  for (const violation of findForbiddenFields(obj)) v.items.push(violation);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return { ok: true, value: input as NavigationCompletedEvent };
+}