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

package/packages/public-runtime/src/integration/g2-action-boundary.ts

@@ -0,0 +1,106 @@
+/**
+ * Closed policy for the evidence-rejected G2 account-interest gap.
+ *
+ * This is deliberately a first-party policy seam, not a G2 client: it has no
+ * endpoint, vendor identifier, browser loader, DOM input, mutable configuration,
+ * or side effect. A future owned destination may consume only an already-emitted,
+ * validated semantic action through this policy.
+ */
+import type { CommerceEvent } from "./events.js";
+import {
+  APPROVED_MARKETING_ACTION_NAMES,
+  type ApprovedMarketingActionName,
+} from "./events.js";
+import {
+  emitManagedActionActivated,
+  type ManagedActionActivationInput,
+  type ManagedAnalyticsEmitResult,
+} from "./managed-analytics.js";
+import type { CommerceEventBroker } from "./commerce-broker.js";
+
+/** Only these two actions are distinct G2 conversion candidates; never aggregate them. */
+export const G2_CONVERSION_ACTION_NAMES = [
+  "user_clicked_contact_sales_mktg",
+  "user_clicked_create_account_mktg",
+] as const satisfies readonly ApprovedMarketingActionName[];
+
+/** These actions remain first-party product/service telemetry and are never G2 eligible. */
+export const INTERNAL_ONLY_ACTION_NAMES = [
+  "user_clicked_login_mktg",
+  "user_clicked_contact_support_consumer_mktg",
+  "user_clicked_contact_support_partner_mktg",
+] as const satisfies readonly ApprovedMarketingActionName[];
+
+export type G2ActionDisposition =
+  | "g2-conversion-eligible"
+  | "internal-only"
+  | "withheld-marketing-consent";
+
+export interface G2ActionBoundaryDecision {
+  readonly actionName: ApprovedMarketingActionName;
+  readonly disposition: G2ActionDisposition;
+}
+
+const G2_CONVERSION_ACTION_SET: ReadonlySet<string> = new Set(G2_CONVERSION_ACTION_NAMES);
+const INTERNAL_ONLY_ACTION_SET: ReadonlySet<string> = new Set(INTERNAL_ONLY_ACTION_NAMES);
+
+function approvedActionName(value: unknown): ApprovedMarketingActionName | undefined {
+  return (APPROVED_MARKETING_ACTION_NAMES as readonly string[]).includes(value as string)
+    ? value as ApprovedMarketingActionName
+    : undefined;
+}
+
+/**
+ * Classify an already-validated first-party action event for any future G2
+ * destination. Invalid/unrelated events are deliberately not classifiable.
+ *
+ * Marketing consent is a separate destination-purpose gate. The underlying
+ * first-party action event is already analytics-consent and broker-dedupe gated.
+ */
+export function decideG2ActionBoundary(event: CommerceEvent): G2ActionBoundaryDecision | undefined {
+  if (event.type !== "storefront.action.activated.v1") return undefined;
+  if (Object.keys(event.data).length !== 1) return undefined;
+  const actionName = approvedActionName(event.data["name"]);
+  if (!actionName) return undefined;
+
+  if (INTERNAL_ONLY_ACTION_SET.has(actionName)) {
+    return { actionName, disposition: "internal-only" };
+  }
+  if (!G2_CONVERSION_ACTION_SET.has(actionName)) return undefined;
+  if (!event.consent.eligiblePurposes.includes("marketing")) {
+    return { actionName, disposition: "withheld-marketing-consent" };
+  }
+  return { actionName, disposition: "g2-conversion-eligible" };
+}
+
+export interface ConfirmedManagedActionInput extends ManagedActionActivationInput {
+  /** The platform handler must establish success; clicks and attempted submits are rejected. */
+  confirmedSuccess: true;
+}
+
+export type ConfirmedManagedActionResult = ManagedAnalyticsEmitResult | {
+  ok: true;
+  emitted: false;
+  skipReason: "not-confirmed-success";
+  deliveries: [];
+};
+
+/**
+ * The only first-party collection entry point intended for the five G2-gap
+ * actions. It does not deliver to G2; it simply refuses non-success activity
+ * before passing the closed `{ name }` event to the existing consented,
+ * idempotent CommerceEventBroker.
+ */
+export function emitConfirmedManagedActionActivated(
+  broker: CommerceEventBroker,
+  input: Omit<ManagedActionActivationInput, "name"> & {
+    name: ApprovedMarketingActionName;
+    confirmedSuccess: boolean;
+  },
+): ConfirmedManagedActionResult {
+  if (input.confirmedSuccess !== true) {
+    return { ok: true, emitted: false, skipReason: "not-confirmed-success", deliveries: [] };
+  }
+  const { confirmedSuccess: _confirmedSuccess, ...activation } = input;
+  return emitManagedActionActivated(broker, activation);
+}

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

@@ -0,0 +1,90 @@
+/**
+ * @tot/public-runtime — the versioned PUBLIC browser-integration contracts.
+ *
+ * The renderer-safe, semver-versioned surface (ADR 0006) that 35+ downstream
+ * cards build on. It is the single shared contract for both tenant-local
+ * configuration and managed apps (ADR 0014 C1 `integration-schema-shared`):
+ * promotion changes ownership and packaging, never the browser contract.
+ *
+ * Every contract here is CLOSED and FAIL-CLOSED — unknown fields, unknown
+ * enum members, malformed shapes, duplicates, and incompatible versions are
+ * rejected, never ignored or assumed safe — and none is secret-bearing (charter
+ * invariant 3, ADR 0018 nonce non-serialization).
+ *
+ * Charter/ADR traceability for the six source-card concerns:
+ *   - environment        → ./environment.ts   (E1 / ADR 0017)
+ *   - global hook + slots → ./phases.ts + ./manifest.ts (S1/S2, ADR 0016)
+ *   - CSP                 → ./csp.ts           (E2 / ADR 0018, 0019)
+ *   - lifecycle           → ./lifecycle.ts + navigation event (invariant 9)
+ *   - migration           → ./manifest.ts configurationMigrations + ./version.ts
+ *   - authority/assurance → ./phases.ts tiers + ./assurance.ts (I1, G1/G2, 0023)
+ *
+ * Contract families:
+ *   - version.ts     — semver contract version + per-family schemaVersion pins
+ *   - result.ts      — the closed/fail-closed validation core
+ *   - secrets.ts     — the no-secret-in-the-browser guard
+ *   - environment.ts — the universal four-stage browser environment
+ *   - phases.ts      — reserved phases, authority tiers, the contribution DAG
+ *   - csp.ts         — exact-origin CSP source contract
+ *   - csp-compiler.ts — version-scoped compiler: curated profiles + advanced origins
+ *   - manifest.ts    — the shared integration declaration (tenant-local + app)
+ *   - plan.ts        — the server-computed effective plan + source references
+ *   - resolve.ts     — the pure resolver that merges declarations into a plan
+ *   - render-phases.ts — the one fixed-phase render engine both mounts consume
+ *   - lifecycle.ts   — the exactly-once MPA lifecycle contract
+ *   - lifecycle-runtime.ts — the browser runtime: exactly-once init, update/dispose,
+ *       error isolation, and the reserved completed-navigation event seam
+ *   - lifecycle-boot.ts — the guarded document.deferred boot binding for `window`
+ *   - events.ts      — the canonical semantic commerce + reserved navigation events
+ *   - events-catalog.ts — per-field owner/purpose/sensitivity + retention classes
+ *   - commerce-broker.ts — the platform-owned client emitter/subscription API:
+ *       server-owned context stamped not caller-set, one-event-per-action dedupe,
+ *       consent-filtered per-subscriber delivery, subscriber-fault isolation,
+ *       and typed iframe-consumer messages
+ *   - assurance.ts   — compliance assurance metadata (non-waivable floor)
+ *   - assurance-decision.ts — the enforcement layer over an assurance record
+ */
+export * from "./version.js";
+export * from "./result.js";
+export { stableStringify as stableIntegrationStringify } from "./digest.js";
+export * from "./secrets.js";
+export * from "./environment.js";
+export * from "./phases.js";
+export * from "./csp.js";
+export * from "./csp-compiler.js";
+export * from "./manifest.js";
+export * from "./plan.js";
+export * from "./resolve.js";
+export * from "./platform-adapters.js";
+export * from "./native-amplitude.js";
+export * from "./native-ga4.js";
+export * from "./platform-adapter-runtime.js";
+export * from "./render-phases.js";
+export * from "./interim-bridge.js";
+export * from "./consent-broker.js";
+export * from "./consent-cmp-demand.js";
+export * from "./consent-config.js";
+export * from "./consent-preview.js";
+export * from "./candidate-evidence.js";
+export * from "./lifecycle.js";
+export * from "./lifecycle-runtime.js";
+export * from "./lifecycle-boot.js";
+export * from "./events.js";
+export * from "./events-catalog.js";
+export * from "./commerce-broker.js";
+export * from "./managed-analytics.js";
+export * from "./managed-analytics-bridge.js";
+export * from "./g2-action-boundary.js";
+export * from "./correlation-token.js";
+export * from "./order-conversion.js";
+export * from "./receipt-measurement.js";
+export * from "./provider-checkout-extension.js";
+export * from "./assurance.js";
+export * from "./assurance-decision.js";
+export * from "./tamper-evidence.js";
+export * from "./tamper-recovery.js";
+export * from "./observability.js";
+export * from "./regulated-parent-cert.js";
+export * from "./promotion-gate.js";
+export * from "./managed-analytics-api-v1.js";
+export * from "./managed-analytics-api-v1.schemas.js";

package/packages/public-runtime/src/integration/interim-bridge.ts

@@ -0,0 +1,138 @@
+/**
+ * The supported interim MARKETING bridge (ext-kernel-07, WS1 roadmap "smallest
+ * supported interim bridge").
+ *
+ * This is the one seam that makes the whole browser-integration kernel observable
+ * end-to-end WITHOUT a page edit or a vendor branch: a tenant-local declaration's
+ * exact-version entry module flows through the resolver → the effective plan
+ * ({@link resolveEffectivePlan}) → the render-phase boot descriptor
+ * ({@link BootDescriptorIntegration}) → the lifecycle runtime, which dynamically
+ * imports and inits it — consent-gated, at a pinned version, in all four
+ * environments. Removing the declaration removes the code, the network, and the CSP
+ * with it (the plan carries no vendor runtime, and `planRevision` moves), so a
+ * rollback leaves no stale effect.
+ *
+ * It is deliberately narrow (ADR 0016/0023 Q6): the bridge is enabled ONLY on
+ * eligible unregulated-marketing tenants. A regulated tenant is REFUSED with an
+ * actionable explanation until a capability-specific certification exists — the
+ * regulated shared-runtime floor is non-waivable, and this bridge never opens an
+ * escape hatch around it. Promote-time enforcement still runs through the full
+ * fail-closed gate (`verifyIntegrationPromotable`); this module is the render-time
+ * tenant-eligibility decision that precedes it.
+ */
+import type { BrowserEnvironment } from "./environment.js";
+import type { EffectivePlan } from "./plan.js";
+import type { ContractViolation } from "./result.js";
+import type { ConsentSnapshot } from "./consent-broker.js";
+import { isPurposeEligible } from "./consent-broker.js";
+import type { BootDescriptorIntegration } from "./render-phases.js";
+import type { AssuranceSurface } from "./assurance.js";
+import { resolveEffectivePlan, type IntegrationDeclarationInput } from "./resolve.js";
+import type { ObligationTenant } from "../compliance-obligations.js";
+import { isRegulated, resolveObligationSurface } from "../compliance-obligations.js";
+import {
+  isRegulatedParentCertified,
+  type RegulatedParentCertification,
+} from "./regulated-parent-cert.js";
+
+/**
+ * Whether an integration's declared consent dependency permits loading its entry
+ * under `snapshot`. An `essential-only` entry always loads; any other entry loads
+ * only once EVERY declared purpose is eligible — so under the default-deny snapshot
+ * (only `essential`) a non-essential loader is held back until consent is granted.
+ * This is the predicate the lifecycle runtime's consent gate uses.
+ */
+export function integrationConsentEligible(
+  integration: Pick<BootDescriptorIntegration, "consent">,
+  snapshot: ConsentSnapshot,
+): boolean {
+  if (integration.consent.loadWhen === "essential-only") return true;
+  return integration.consent.purposes.every((purpose) => isPurposeEligible(snapshot, purpose));
+}
+
+/** Why the interim bridge refused to enable for a tenant — actionable, non-secret. */
+export interface InterimBridgeRefusal {
+  code: "regulated-tenant-not-certified";
+  /** The tenant's resolved compliance-authority surface. */
+  surface: AssuranceSurface;
+  /** An operator-facing explanation of the refusal and what unblocks it. */
+  message: string;
+}
+
+/**
+ * The interim bridge result: a resolved plan for an eligible tenant, an actionable
+ * refusal for a regulated one, or the resolver's fail-closed violations for an
+ * invalid declaration set. `reason` discriminates the two failure shapes.
+ */
+export type InterimBridgeResult =
+  | { ok: true; plan: EffectivePlan }
+  | { ok: false; reason: "regulated-refused"; refusal: InterimBridgeRefusal }
+  | { ok: false; reason: "invalid-plan"; violations: ContractViolation[] };
+
+/** Everything the bridge needs to decide eligibility and resolve the plan. */
+export interface InterimBridgeInput {
+  tenantPublicId: string;
+  /** The tenant's authoritative config — the ONLY source of its regulated classification. */
+  tenant: ObligationTenant;
+  environment: BrowserEnvironment;
+  declarations: readonly IntegrationDeclarationInput[];
+  /**
+   * G2: the regulated elevated-parent certification artifact for a regulated tenant.
+   * The bridge NEVER accepts a raw "certified" boolean — it runs
+   * {@link decideRegulatedParentCert} itself (via {@link isRegulatedParentCertified}),
+   * so `certifiedImmutable` has a SINGLE ORIGIN: a regulated tenant is enabled ONLY
+   * when the cert clears every clause (pinned, undrifted from `servedDigest`, every
+   * server-derived obligation proven). Absent/failed ⇒ the decision fails closed and
+   * the tenant stays refused. This is the WS2 forward seam, not a per-tenant bypass.
+   */
+  regulatedCertification?: RegulatedParentCertification | null;
+  /**
+   * The content digest of the artifact currently resolved to serve — the drift anchor
+   * the certification decision compares against its pinned digest. When it differs, the
+   * served code has drifted and the certification no longer holds (fail closed).
+   */
+  servedDigest?: string;
+}
+
+/**
+ * Resolve the interim bridge's effective plan for a tenant, refusing a regulated one
+ * until certified. On an eligible tenant it delegates to the pure, hot-path
+ * {@link resolveEffectivePlan} (which fail-closes on an invalid/partial declaration
+ * set), so an eligible tenant's plan is exactly the kernel plan every mount serves —
+ * the bridge adds only the tenant-eligibility gate, not a second plan shape.
+ */
+export function resolveInterimBridgePlan(input: InterimBridgeInput): InterimBridgeResult {
+  const surface = resolveObligationSurface(input.tenant);
+
+  // The certification is the SINGLE ORIGIN of `certifiedImmutable`: derive it from the
+  // decision (never a raw external flag), so a regulated tenant is enabled only when the
+  // cert actually clears every clause. Absent/failed ⇒ false ⇒ refused.
+  const regulatedCertified = isRegulatedParentCertified(input.regulatedCertification, {
+    tenant: input.tenant,
+    servedDigest: input.servedDigest,
+  });
+
+  if (isRegulated(input.tenant) && !regulatedCertified) {
+    return {
+      ok: false,
+      reason: "regulated-refused",
+      refusal: {
+        code: "regulated-tenant-not-certified",
+        surface,
+        message:
+          `The interim marketing bridge is not enabled for regulated tenants (resolved surface ` +
+          `"${surface}"). A regulated parent tier requires an immutable, version-pinned, ` +
+          `capability-specific certification — a mere acknowledgement cannot waive the ` +
+          `non-waivable regulated shared-runtime floor. Complete WS2 certification to enable it.`,
+      },
+    };
+  }
+
+  const result = resolveEffectivePlan({
+    tenantPublicId: input.tenantPublicId,
+    environment: input.environment,
+    declarations: input.declarations,
+  });
+  if (!result.ok) return { ok: false, reason: "invalid-plan", violations: result.violations };
+  return { ok: true, plan: result.value };
+}

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -0,0 +1,317 @@
+/**
+ * The thin browser binding that boots the {@link IntegrationLifecycle} from the
+ * document.deferred phase (ext-kernel-04 emits the `document.deferred` boundary; this is
+ * what its deferred script invokes). It is deliberately small and structural: it reads
+ * the renderer-published boot descriptor global, guarantees ONE lifecycle per document
+ * with a window-level singleton (so a nested layout that re-runs the boot island cannot
+ * double-init), wires same-document navigations to the reserved completed-navigation
+ * event, disposes on document teardown, and is a guarded no-op off the browser.
+ *
+ * The entry module for each integration is the same-origin, exact-version asset the
+ * boot descriptor carries (`integration.entry.url`): the default loader dynamically
+ * imports exactly that URL into the PARENT document and checks it exports the lifecycle
+ * contract, so no page edit or vendor branch is needed — the URL flows through the plan.
+ * Reviewed `platform-adapter` entries are admitted first through the closed runtime
+ * registry, which verifies their exact origin/tier/app/version/URL/format marker and
+ * constructs bundled platform code with host-owned capabilities. Every other entry goes
+ * through the authority-tier loader: it loads ONLY an `elevated-parent` entry (whose
+ * honest, review-only contract IS arbitrary parent-document JavaScript) and REFUSES every
+ * other tier. A `sandbox`-tier entry —
+ * whose contract is a null-origin iframe reachable only through the typed postMessage
+ * broker — is refused here and held back until the iframe host that actually isolates
+ * it ships, so third-party code labeled "sandboxed" is never executed with the parent
+ * authority its label does not grant. Loading is also consent-gated: the binding reads
+ * the renderer-inlined default-deny consent snapshot and holds a non-essential entry
+ * back until its declared purposes are eligible. With an environment-only plan there
+ * are no integrations, so the runtime boots inert and ready.
+ */
+import { IntegrationLifecycle, type IntegrationModuleLoader } from "./lifecycle-runtime.js";
+import type { LifecycleObserver } from "./lifecycle-runtime.js";
+import type { IntegrationLifecycleModule } from "./lifecycle.js";
+import type { BootDescriptorIntegration, IntegrationBootDescriptor } from "./render-phases.js";
+import { INTEGRATION_PLAN_GLOBAL, INTEGRATION_CONSENT_GLOBAL } from "./render-phases.js";
+import { parseConsentSnapshot, defaultConsentSnapshot, type ConsentSnapshot } from "./consent-broker.js";
+import { integrationConsentEligible } from "./interim-bridge.js";
+import type { NavigationCompletedEvent, NavigationKind } from "./events.js";
+import { CommerceEventBroker } from "./commerce-broker.js";
+import { validateBrowserEnvironment, BROWSER_ENVIRONMENT_GLOBAL, type BrowserEnvironment } from "./environment.js";
+import { makePlatformAdapterRuntimeLoader } from "./platform-adapter-runtime.js";
+
+/** The window property holding the single per-document lifecycle (idempotent boot guard). */
+export const LIFECYCLE_SINGLETON_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE__";
+/**
+ * An optional window-published loader the entry-asset layer may install to OVERRIDE the
+ * fail-closed same-origin default. It is the seam the null-origin sandboxed-iframe host
+ * (the tracked F3 follow-up) installs to actually isolate a `sandbox`-tier entry; until
+ * that host ships the seam is unused and the default loader refuses the sandbox tier.
+ */
+export const LIFECYCLE_MODULE_LOADER_GLOBAL = "__TOT_INTEGRATION_MODULE_LOADER__";
+/** An optional window-published sink for the completed-navigation event. */
+export const LIFECYCLE_NAVIGATION_SINK_GLOBAL = "__TOT_INTEGRATION_NAVIGATION__";
+
+/** The narrow slice of `window` the binding depends on — structural, for edge-safe typing. */
+export interface LifecycleWindow {
+  location: { pathname: string; search: string; hash: string; href: string };
+  addEventListener(type: string, listener: (event: unknown) => void): void;
+  fetch?: typeof fetch;
+  [key: string]: unknown;
+}
+
+export interface BootLifecycleOptions {
+  loadModule?: IntegrationModuleLoader;
+  /** Consent gate override; defaults to the renderer-inlined default-deny snapshot. */
+  isEligible?: (integration: BootDescriptorIntegration) => boolean;
+  emitNavigation?: (event: NavigationCompletedEvent) => void;
+  observe?: LifecycleObserver;
+  /**
+   * The four-stage browser environment handed to every integration's `init`/`update`
+   * context; defaults to the renderer-published `__TOT_INTEGRATION_ENV__` global
+   * (fail closed to the descriptor-derived fallback if absent/tampered).
+   */
+  environment?: BrowserEnvironment;
+  /**
+   * Reads the current consent snapshot handed to every integration's `init`/`update`
+   * context; defaults to the renderer-published `__TOT_INTEGRATION_CONSENT__` global
+   * (fail closed to the default-deny snapshot).
+   */
+  getConsentSnapshot?: () => ConsentSnapshot;
+  /**
+   * The commerce-event broker whose scoped, receive-only subscribe handle is placed on
+   * each integration's lifecycle context; defaults to one constructed from the boot
+   * descriptor's server-derived trusted context (tenant/environment/surface) and the
+   * resolved consent snapshot source, so every envelope is server-stamped and
+   * consent-filtered exactly like the platform path. Injectable for tests.
+   */
+  commerceBroker?: CommerceEventBroker;
+  /** Host-owned fetch capability for reviewed first-party platform adapters. */
+  fetchCapability?: typeof fetch;
+  /** Entry import capability; injectable for tests and non-browser hosts. */
+  importModule?: (url: string) => Promise<unknown>;
+}
+
+/**
+ * Narrow the namespace of a dynamically-imported entry module to the lifecycle
+ * contract: an `init()` on the module namespace, or on its default export. Anything
+ * else is not a valid integration entry (fail closed — the caller rejects the load).
+ */
+function asLifecycleModule(ns: unknown): IntegrationLifecycleModule | null {
+  const candidate = (ns as { default?: unknown })?.default ?? ns;
+  if (candidate && typeof (candidate as { init?: unknown }).init === "function") {
+    return candidate as IntegrationLifecycleModule;
+  }
+  return null;
+}
+
+/**
+ * The one authority tier the same-origin (parent-realm) loader may run: an
+ * `elevated-parent` entry's honest contract IS arbitrary parent-document JavaScript, so
+ * importing it into the parent grants exactly what its (review-only) label already
+ * declares. Every other tier — above all `sandbox`, whose contract is a null-origin
+ * iframe reachable only through the typed postMessage broker — is refused here, so its
+ * isolation is never silently downgraded to full parent access.
+ */
+const PARENT_REALM_TIER = "elevated-parent" as const;
+
+/**
+ * Build the same-origin entry-module loader: dynamically import an integration's
+ * declared, exact-version `entry.url` into the PARENT document and return its lifecycle
+ * module. Vendor-neutral — it imports whatever same-origin URL the plan resolved, never
+ * a hardcoded vendor path. `importModule` is injected so the loader is testable without
+ * a live network; it defaults to a native dynamic `import()`.
+ *
+ * FAIL-CLOSED BY TIER (design-partner finding F3): a parent-realm import gives the entry
+ * full parent-document authority, so the loader refuses any tier but `elevated-parent`
+ * BEFORE importing — a `sandbox`-tier entry throws without ever being fetched or
+ * evaluated, so code labeled "sandboxed" cannot run in the parent while its isolating
+ * iframe host is still the tracked follow-up. The throw is caught by the runtime's
+ * per-integration load isolation: the entry never becomes active, the page is unaffected,
+ * and every other integration still boots.
+ */
+export function makeSameOriginEntryLoader(
+  importModule: (url: string) => Promise<unknown> = (url) => import(/* @vite-ignore */ url),
+): IntegrationModuleLoader {
+  return async (integration) => {
+    if (integration.executionTier !== PARENT_REALM_TIER) {
+      throw new Error(
+        `Refusing to load "${integration.appId}@${integration.version}" (tier ` +
+          `"${integration.executionTier}") into the parent document: the same-origin loader ` +
+          `only runs the "${PARENT_REALM_TIER}" tier. A "sandbox"-tier entry must run inside a ` +
+          `null-origin iframe reachable only through the typed postMessage broker; that ` +
+          `isolating host is not yet wired, so the entry is held fail-closed rather than run ` +
+          `with parent-document authority its tier does not grant.`,
+      );
+    }
+    const ns = await importModule(integration.entry.url);
+    const mod = asLifecycleModule(ns);
+    if (!mod) {
+      throw new Error(
+        `Entry module "${integration.entry.url}" for "${integration.appId}@${integration.version}" ` +
+          `does not export the integration lifecycle contract (init()).`,
+      );
+    }
+    return mod;
+  };
+}
+
+/** The default same-origin entry loader, over a native dynamic import. */
+export const sameOriginEntryLoader: IntegrationModuleLoader = makeSameOriginEntryLoader();
+
+/**
+ * Construct the per-document commerce-event broker from the boot descriptor's
+ * server-derived trusted context (tenant/environment/surface) and the resolved consent
+ * snapshot source — so every envelope the broker stamps and every per-subscriber
+ * consent filter matches the platform path exactly. The broker backs the receive-only
+ * subscribe handle each sandbox entry gets; it never hands emit power to a vendor.
+ */
+function makeDocumentCommerceBroker(
+  descriptor: IntegrationBootDescriptor,
+  getConsentSnapshot: () => ConsentSnapshot,
+): CommerceEventBroker {
+  return new CommerceEventBroker({
+    trusted: {
+      tenant: descriptor.tenantPublicId,
+      environment: descriptor.environment,
+      siteSurface: descriptor.siteSurface,
+    },
+    source: `//${descriptor.tenantPublicId}`,
+    consentSnapshot: getConsentSnapshot,
+  });
+}
+
+function readDescriptor(win: LifecycleWindow): IntegrationBootDescriptor | null {
+  const descriptor = win[INTEGRATION_PLAN_GLOBAL];
+  if (!descriptor || typeof descriptor !== "object") return null;
+  return descriptor as IntegrationBootDescriptor;
+}
+
+/**
+ * Read the current consent snapshot off the renderer-inlined global. A missing or
+ * tampered snapshot falls back to the default-deny snapshot (fail closed). This is
+ * the ONE read both the consent gate and the `init`/`update` context use, so they
+ * can never disagree about the current snapshot.
+ */
+function readConsentSnapshot(win: LifecycleWindow): ConsentSnapshot {
+  return parseConsentSnapshot(win[INTEGRATION_CONSENT_GLOBAL]) ?? defaultConsentSnapshot();
+}
+
+/**
+ * Read the renderer-published four-stage browser environment off `__TOT_INTEGRATION_ENV__`.
+ * `undefined` when the global is absent or fails {@link validateBrowserEnvironment} (fail
+ * closed) — the caller falls back to the descriptor-derived default.
+ */
+function readBrowserEnvironment(win: LifecycleWindow): BrowserEnvironment | undefined {
+  const result = validateBrowserEnvironment(win[BROWSER_ENVIRONMENT_GLOBAL]);
+  return result.ok ? result.value : undefined;
+}
+
+/**
+ * The default consent gate: eligible iff the integration's declared purposes are all
+ * eligible under the renderer-inlined consent snapshot. A missing or tampered snapshot
+ * global falls back to the default-deny snapshot, so a non-essential entry stays gated
+ * (fail closed). A CMP/native banner that later grants a purpose updates this global and
+ * calls `lifecycle.update("consent-changed")`, which loads the newly-eligible entry.
+ */
+function defaultConsentGate(
+  win: LifecycleWindow,
+): (integration: BootDescriptorIntegration) => boolean {
+  return (integration) => integrationConsentEligible(integration, readConsentSnapshot(win));
+}
+
+/**
+ * Boot the lifecycle for `win` exactly once. A second call returns the same instance
+ * (nested-layout safety). Returns `null` when there is no boot descriptor to act on.
+ */
+export function bootIntegrationLifecycle(
+  win: LifecycleWindow,
+  options: BootLifecycleOptions = {},
+): IntegrationLifecycle | null {
+  const existing = win[LIFECYCLE_SINGLETON_GLOBAL];
+  if (existing instanceof IntegrationLifecycle) return existing;
+
+  const descriptor = readDescriptor(win);
+  if (!descriptor) return null;
+
+  const hostFetch = options.fetchCapability ??
+    (typeof win.fetch === "function" ? win.fetch.bind(win) : undefined);
+  const fallbackLoader = options.importModule
+    ? makeSameOriginEntryLoader(options.importModule)
+    : sameOriginEntryLoader;
+  const ordinaryLoader =
+    options.loadModule ??
+    (win[LIFECYCLE_MODULE_LOADER_GLOBAL] as IntegrationModuleLoader | undefined) ??
+    fallbackLoader;
+  // Platform authority is resolved before any caller/window override: exact registry
+  // matches run; unknown/mismatched platform claims fail closed without delegation.
+  const loadModule = makePlatformAdapterRuntimeLoader({
+    fetchCapability: hostFetch,
+    importModule: options.importModule,
+    fallback: ordinaryLoader,
+  });
+
+  const isEligible = options.isEligible ?? defaultConsentGate(win);
+
+  const emitNavigation =
+    options.emitNavigation ??
+    (win[LIFECYCLE_NAVIGATION_SINK_GLOBAL] as ((e: NavigationCompletedEvent) => void) | undefined);
+
+  const environment = options.environment ?? readBrowserEnvironment(win);
+  const getConsentSnapshot = options.getConsentSnapshot ?? (() => readConsentSnapshot(win));
+  const commerceBroker =
+    options.commerceBroker ?? makeDocumentCommerceBroker(descriptor, getConsentSnapshot);
+
+  const lifecycle = new IntegrationLifecycle({
+    descriptor,
+    loadModule,
+    isEligible,
+    emitNavigation,
+    observe: options.observe,
+    environment,
+    getConsentSnapshot,
+    commerceBroker,
+  });
+  win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
+
+  wireNavigation(win, lifecycle);
+  wireTeardown(win, lifecycle);
+  void lifecycle.init();
+  return lifecycle;
+}
+
+/**
+ * Wire same-document navigations to the reserved completed-navigation event. In a
+ * traditional MPA a real document load re-inits by construction, so only the two
+ * navigations that DON'T reload the document — hash changes and history back/forward —
+ * need a completed-navigation signal, and neither re-initializes integrations.
+ */
+function wireNavigation(win: LifecycleWindow, lifecycle: IntegrationLifecycle): void {
+  let lastPath = win.location.pathname + win.location.hash;
+  win.addEventListener("hashchange", () => {
+    const to = win.location.pathname + win.location.hash;
+    lifecycle.notifyNavigationCompleted({ from: lastPath, to, kind: "hash" });
+    lastPath = to;
+  });
+  win.addEventListener("popstate", () => {
+    const to = win.location.pathname + win.location.hash;
+    const kind: NavigationKind = "back-forward";
+    lifecycle.notifyNavigationCompleted({ from: lastPath, to, kind });
+    lastPath = to;
+  });
+}
+
+/** Dispose the lifecycle when the document is torn down, so integrations clean up once. */
+function wireTeardown(win: LifecycleWindow, lifecycle: IntegrationLifecycle): void {
+  win.addEventListener("pagehide", () => {
+    void lifecycle.dispose();
+  });
+}
+
+/**
+ * The document.deferred entrypoint: boot from the ambient `window`. A guarded no-op when
+ * there is no browser (SSR, the edge Worker bundle, tests that import the module).
+ */
+export function bootIntegrationLifecycleFromDocument(
+  options: BootLifecycleOptions = {},
+): IntegrationLifecycle | null {
+  if (typeof window === "undefined") return null;
+  return bootIntegrationLifecycle(window as unknown as LifecycleWindow, options);
+}