@tokenoftrust/storefront-runner 2.0.22 → 2.0.24

package/apps/storefront/astro.config.mjs

@@ -58,6 +58,7 @@ import preact from "@astrojs/preact";
 import tailwindcss from "@tailwindcss/vite";
 import { tenantHotReload } from "./dev-plugins/tenant-hot-reload.mjs";
 import { materializeGuard } from "./integrations/materialize-guard.mjs";
+import { lifecycleHostAsset } from "./integrations/lifecycle-host-asset.mjs";
 
 // SSR on Cloudflare Workers. `output: 'server'` because every response is
 // tenant-resolved at the edge from the Host header (see src/middleware).
@@ -94,6 +95,10 @@ export default defineConfig({
     // resolves from KV/R2 at request time. The same integration becomes strict
     // only when TOT_BUILD_TENANTS names a per-tenant static publish input.
     materializeGuard(),
+    // The document.deferred lifecycle host, emitted as one self-contained module at a
+    // stable same-origin URL so BOTH document mounts load the same boot — the raw
+    // marketing mount has no bundler to hoist a module import through.
+    lifecycleHostAsset(),
     preact({ compat: true }),
     // Astro's file-based router ignores ANY path segment starting with "_" (see
     // `astro/dist/core/routing/create-manifest.js`), so a page literally named

package/apps/storefront/integrations/lifecycle-host-asset.mjs

@@ -0,0 +1,125 @@
+/**
+ * Emit the document.deferred lifecycle host as ONE self-contained module at a stable
+ * same-origin URL, so both document mounts can load the same host.
+ *
+ * WHY NOT A ROLLUP CHUNK. `Layout.astro` gets its client code through Astro's bundler,
+ * which hashes filenames and splits shared modules into sibling chunks. The raw marketing
+ * mount can use neither: it serves a tenant's own document verbatim, so it needs a URL it
+ * can hardcode. And a SPLIT bundle is actively unsafe here — a published static bundle
+ * (`scripts/publish/materialize-tenant.mjs`) copies only what the rendered HTML references
+ * and follows CSS `url()` but NOT JavaScript imports, so a sibling chunk would resolve on
+ * the Cloudflare plane and 404 on the S3/CloudFront one. That asymmetry is exactly the
+ * both-CDNs failure this repo treats as an invariant, and nothing downstream would report
+ * it: validate-bundle only checks HTML-referenced paths.
+ *
+ * So the host is bundled ONCE by esbuild with no code splitting, and this REFUSES to emit
+ * anything carrying an import. A single import-free file behaves identically on both
+ * providers by construction.
+ *
+ * It is an Astro INTEGRATION rather than a bare Vite plugin because Astro is the only
+ * thing that knows where the client output actually goes: every one of Astro's build
+ * passes — the client pass included — runs with `build.ssr === true`, so a Vite plugin
+ * cannot tell them apart, while `config.build.client` says it outright.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LIFECYCLE_HOST_ASSET_PATH } from "@tot/public-runtime/integration/lifecycle-host-asset";
+
+const HOST_ENTRY = fileURLToPath(
+  new URL(
+    "../../../packages/public-runtime/src/integration/lifecycle-host-entry.ts",
+    import.meta.url,
+  ),
+);
+
+/**
+ * Bundle the host to a single self-contained ES module.
+ *
+ * esbuild is resolved through `astro` (a direct dependency of this app, always present
+ * whenever this integration runs) rather than declared again here, so its version cannot
+ * drift from the one the build already uses.
+ * @returns {Promise<string>}
+ */
+export async function bundleLifecycleHost() {
+  const require = createRequire(import.meta.url);
+  const esbuild = createRequire(require.resolve("astro/package.json"))("esbuild");
+  const result = await esbuild.build({
+    entryPoints: [HOST_ENTRY],
+    bundle: true,
+    write: false,
+    metafile: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2022",
+    minify: true,
+    treeShaking: true,
+    legalComments: "none",
+    sourcemap: false,
+    logLevel: "silent",
+  });
+  if (result.outputFiles.length !== 1) {
+    throw new Error(
+      `The lifecycle host bundled to ${result.outputFiles.length} files; it must be one ` +
+        `self-contained module (a sibling chunk 404s on the S3/CloudFront plane).`,
+    );
+  }
+  // The metafile is authoritative about imports in a way a regex over minified code is
+  // not: any entry here is a file the browser would have to fetch separately.
+  for (const output of Object.values(result.metafile.outputs)) {
+    const external = (output.imports ?? []).filter((i) => i.kind !== "file-loader");
+    if (external.length > 0) {
+      throw new Error(
+        `The lifecycle host bundle imports ${external.map((i) => i.path).join(", ")}; it ` +
+          `must carry no imports, because the static publish pipeline does not follow them.`,
+      );
+    }
+  }
+  return result.outputFiles[0].text;
+}
+
+/**
+ * @returns {import("astro").AstroIntegration}
+ */
+export function lifecycleHostAsset() {
+  /** @type {URL | null} */
+  let clientDir = null;
+
+  return {
+    name: "tot-lifecycle-host-asset",
+    hooks: {
+      "astro:config:done": ({ config }) => {
+        clientDir = config.build.client;
+      },
+
+      // Dev serves it from memory: the raw marketing mount bypasses Astro's pipeline
+      // entirely, so without this the host 404s in `astro dev` and `tot dev` on exactly
+      // the pages this asset exists to cover. Rebundled per request (esbuild is fast) so
+      // an edit to the runtime shows up on reload rather than being pinned to server boot.
+      "astro:server:setup": ({ server }) => {
+        server.middlewares.use((req, res, next) => {
+          const path = (req.url ?? "").split("?")[0];
+          if (path !== `/${LIFECYCLE_HOST_ASSET_PATH}`) return next();
+          bundleLifecycleHost().then(
+            (code) => {
+              res.setHeader("content-type", "text/javascript; charset=utf-8");
+              res.setHeader("cache-control", "no-store");
+              res.end(code);
+            },
+            (error) => next(error),
+          );
+        });
+      },
+
+      "astro:build:done": async ({ logger }) => {
+        if (!clientDir) throw new Error("the lifecycle host has no resolved client output dir");
+        const code = await bundleLifecycleHost();
+        const target = fileURLToPath(new URL(LIFECYCLE_HOST_ASSET_PATH, clientDir));
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, code, "utf8");
+        logger.info(`lifecycle host → /${LIFECYCLE_HOST_ASSET_PATH} (${code.length} bytes)`);
+      },
+    },
+  };
+}

package/apps/storefront/src/layouts/Layout.astro

@@ -618,16 +618,14 @@ const footerWidgets = await renderWidgetSlot(
         entry in lib/cspStaticHashes.ts. */}
     <script is:inline nonce={cspNonce} set:html={INTERACTION_TRACKING_BOOT_JS}></script>
 
-    {/* document.deferred global-entry boundary (ext-kernel-04) — the last phase,
-        the renderer-owned mount point for the deferred integration entry. */}
+    {/* document.deferred global-entry boundary (ext-kernel-04) — the last phase, the
+        renderer-owned mount point for the deferred integration entry. This region also
+        CARRIES the lifecycle host tag (ext-kernel-05), which initializes the plan's
+        integrations exactly once per document, emits the governed page view, wires the
+        reserved completed-navigation event, and disposes on teardown; a no-op for an
+        empty plan. It ships with the phase markup rather than as a per-mount addition,
+        so the same bytes reach the raw marketing mount — which serves a tenant's
+        document verbatim and has no bundler to hoist a module import through. */}
     <Fragment set:html={integrationPhases.bodyDeferred} />
-
-    {/* document.deferred lifecycle boot (ext-kernel-05) — initializes the plan's
-        integrations exactly once per document, wires the reserved completed-
-        navigation event, and disposes on teardown; a no-op for an empty plan. */}
-    <script>
-      import { bootIntegrationLifecycleFromDocument } from "@tot/public-runtime";
-      bootIntegrationLifecycleFromDocument();
-    </script>
   </body>
 </html>

package/apps/storefront/src/lib/shared/viewerGrant.ts

@@ -0,0 +1,166 @@
+/**
+ * Viewer ship-grant resolver (security-critical) — resolve a signed-in developer
+ * VIEWER's REAL, owner-revocable ship capability over a tenant, LIVE from the MCP
+ * subject-capability store. This is the near-side read of the Step-1 tot-mcp seam:
+ *
+ *   GET `${origin}/api/internal/dev-access/subject-capability?subject=<email>&tenant=<appDomain>&app=storefront`
+ *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (NOT a bearer)
+ *   → 200 { capability: "ship-on-behalf" | "preview-access" }
+ *        · an ABSENT / REVOKED grant answers `preview-access`
+ *        · a store fault answers 502
+ *
+ * WHY it exists (the security constraint): a normally-invited developer's COARSE
+ * role is `preview-access`, NOT ship — the coarse "developer" role collapses to
+ * member. ship-on-behalf is a SEPARATE, explicit, OWNER-REVOCABLE grant. So the
+ * viewer/browser ship path must NEVER map the coarse role → ship and must NEVER
+ * trust a client-supplied `x-tot-capability` header; it resolves the REAL grant
+ * here, LIVE (no cache that could outlive a revoke).
+ *
+ * FAIL-CLOSED, TOTAL, NEVER THROWS: an unconfigured seam (no URL/secret), a missing
+ * subject/tenant, any non-2xx (INCLUDING 502), an unparseable body, an unexpected
+ * capability value, or a transport/timeout fault ALL resolve to `preview-access` —
+ * the deny default. Only an explicit `200 { capability: "ship-on-behalf" }` grants
+ * ship. This mirrors `dev/previewStatus.ts` + `grants/developerInvites.ts`'s
+ * `recordDeveloperAppBinding` transport (same MCP-origin + service-secret seam);
+ * it keeps its OWN small transport rather than importing another cluster's copy so
+ * the two stay decoupled (the same reason previewStatus duplicates its transport).
+ *
+ * The MCP HOST is the ORIGIN of `MCP_APP_BINDING_URL` — the same tier the invite
+ * app-binding WRITE (`recordDeveloperAppBinding`) targets, so this READ and that
+ * WRITE always agree on which subject-capability store they speak to.
+ */
+import { readEnv } from "@/lib/env";
+import type { Capability } from "./capability.js";
+
+/** Minimal GET transport (mirrors `dev/previewStatus.ts` — decoupled by design). */
+export interface ViewerShipGrantGetTransport {
+  get(
+    url: string,
+    headers: Record<string, string>,
+  ): Promise<{ status: number; json(): Promise<unknown> }>;
+}
+
+/** Default transport: JSON `fetch` GET. */
+export class FetchShipGrantTransport implements ViewerShipGrantGetTransport {
+  async get(url: string, headers: Record<string, string>) {
+    // Bounded: this GET runs during admin-page SSR (AdminPublishTab frontmatter, on
+    // every admin tab), so an unbounded hang stalls the whole document stream. A
+    // timeout aborts to the documented deny-default (the resolver maps any transport/
+    // timeout fault to `preview-access`) — never a render-blocking wait on a slow MCP.
+    const res = await fetch(url, { method: "GET", headers, signal: AbortSignal.timeout(2500) });
+    return { status: res.status, json: () => res.json() };
+  }
+}
+
+/** Injectable deps so the resolver is unit-testable without a live MCP. */
+export interface ViewerShipGrantDeps {
+  transport?: ViewerShipGrantGetTransport;
+}
+
+/** The Step-1 subject-capability reader path (mounted OUTSIDE the session guard). */
+const SUBJECT_CAPABILITY_PATH = "/api/internal/dev-access/subject-capability";
+
+/** The viewer's blog-contribute capability — a NEW, blog-scoped projection kept OUT
+ * of the forge `Capability` union (which stays exactly two rungs). `ship-on-behalf`
+ * supersets contribute, so a ship grant also yields `"blog-contribute"` here. */
+export type ViewerContributeCapability = "preview-access" | "blog-contribute";
+
+/** The raw recognized capability read off the subject-capability seam. The private
+ * transport whitelists BOTH grant literals; the public wrappers narrow it. */
+type RawViewerCapability = "preview-access" | "blog-contribute" | "ship-on-behalf";
+
+/**
+ * ONE live subject-capability lookup, returning the raw whitelisted capability.
+ * FAIL-CLOSED, TOTAL, NEVER THROWS: an unconfigured seam (no URL/secret), a missing
+ * subject/tenant, any non-2xx (INCLUDING 502), an unparseable body, an unexpected
+ * capability value, or a transport/timeout fault ALL resolve to `"preview-access"` —
+ * the deny default. Only an explicit `200 { capability: "ship-on-behalf" }` or
+ * `200 { capability: "blog-contribute" }` returns a grant literal.
+ */
+async function resolveRawViewerCapability(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<RawViewerCapability> {
+  const subject = (email ?? "").trim().toLowerCase();
+  const tenant = (appDomain ?? "").trim();
+  if (!subject || !tenant) return "preview-access";
+
+  const bindingUrl = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  // Unconfigured seam → deny (the MCP route is only mounted once the secret exists).
+  if (!bindingUrl || !secret) return "preview-access";
+
+  let endpoint: string;
+  try {
+    endpoint = `${new URL(bindingUrl).origin}${SUBJECT_CAPABILITY_PATH}`;
+  } catch {
+    return "preview-access";
+  }
+  const full =
+    `${endpoint}?subject=${encodeURIComponent(subject)}` +
+    `&tenant=${encodeURIComponent(tenant)}&app=storefront`;
+
+  const transport = deps.transport ?? new FetchShipGrantTransport();
+  let res: { status: number; json(): Promise<unknown> };
+  try {
+    res = await transport.get(full, { "x-mcp-service-secret": secret });
+  } catch {
+    // Transport / timeout fault — fail closed.
+    return "preview-access";
+  }
+  // Any non-2xx (incl. 502 store fault, 401 unmounted, 404) → deny.
+  if (res.status < 200 || res.status >= 300) return "preview-access";
+
+  let payload: unknown;
+  try {
+    payload = await res.json();
+  } catch {
+    return "preview-access";
+  }
+  const capability = (payload as Record<string, unknown> | null)?.capability;
+  // Whitelist: ONLY the explicit grant literals admit; anything else is deny-default.
+  if (capability === "ship-on-behalf") return "ship-on-behalf";
+  if (capability === "blog-contribute") return "blog-contribute";
+  return "preview-access";
+}
+
+/**
+ * Resolve the viewer's LIVE ship capability over `appDomain`. Returns the granted
+ * `Capability` — `"ship-on-behalf"` ONLY on an explicit `200 { capability:
+ * "ship-on-behalf" }`; EVERYTHING else (unconfigured, absent, 502, timeout,
+ * malformed, unexpected value) fail-closes to `"preview-access"`. Never throws.
+ *
+ * @param email     the signed-in viewer's email (the subject-capability store key)
+ * @param appDomain the resolved tenant the capability is scoped to (server-derived)
+ */
+export async function resolveViewerShipCapability(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<Capability> {
+  const raw = await resolveRawViewerCapability(email, appDomain, deps);
+  return raw === "ship-on-behalf" ? "ship-on-behalf" : "preview-access";
+}
+
+/**
+ * Resolve the viewer's LIVE blog-contribute capability over `appDomain`, from the
+ * SAME subject-capability seam the ship resolver reads. Returns `"blog-contribute"`
+ * ONLY on an explicit `200 { capability: "blog-contribute" }` OR `200 { capability:
+ * "ship-on-behalf" }` (ship supersets contribute); EVERYTHING else (unconfigured,
+ * absent, 502, timeout, malformed, unexpected value) fail-closes to
+ * `"preview-access"`. Never throws. Mirrors `resolveViewerShipCapability` exactly.
+ *
+ * @param email     the signed-in viewer's email (the subject-capability store key)
+ * @param appDomain the resolved tenant the capability is scoped to (server-derived)
+ */
+export async function resolveViewerContributeCapability(
+  email: string | null | undefined,
+  appDomain: string | null | undefined,
+  deps: ViewerShipGrantDeps = {},
+): Promise<ViewerContributeCapability> {
+  const raw = await resolveRawViewerCapability(email, appDomain, deps);
+  return raw === "blog-contribute" || raw === "ship-on-behalf"
+    ? "blog-contribute"
+    : "preview-access";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.0.22",
+  "version": "2.0.24",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -9,7 +9,8 @@
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./blog-visibility": "./src/blog-visibility.mjs"
+    "./blog-visibility": "./src/blog-visibility.mjs",
+    "./integration/lifecycle-host-asset": "./src/integration/lifecycle-host-asset.mjs"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

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

@@ -24,6 +24,13 @@
  * 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.
+ *
+ * The binding also constructs this document's managed-analytics bridge over the same
+ * commerce broker the adapters subscribe to, and hands the lifecycle the bootstrap
+ * page-view input built from the host document (path + minimized attribution). An
+ * adapter's subscription is receive-only, so this is what an active analytics
+ * integration actually receives — without it every adapter loads, subscribes, and then
+ * waits on a broker nothing emits into.
  */
 import { IntegrationLifecycle, type IntegrationModuleLoader } from "./lifecycle-runtime.js";
 import type { LifecycleObserver } from "./lifecycle-runtime.js";
@@ -36,6 +43,8 @@ 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";
+import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
+import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
 
 /** The window property holding the single per-document lifecycle (idempotent boot guard). */
 export const LIFECYCLE_SINGLETON_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE__";
@@ -54,6 +63,12 @@ export interface LifecycleWindow {
   location: { pathname: string; search: string; hash: string; href: string };
   addEventListener(type: string, listener: (event: unknown) => void): void;
   fetch?: typeof fetch;
+  /**
+   * Read ONLY for the referrer the managed page view minimizes to a bare origin. The
+   * analytics data allowlist accepts no other document state — no title, no DOM, no
+   * globals — so this is deliberately the narrowest slice that supports attribution.
+   */
+  document?: { referrer?: string };
   [key: string]: unknown;
 }
 
@@ -83,6 +98,14 @@ export interface BootLifecycleOptions {
    * consent-filtered exactly like the platform path. Injectable for tests.
    */
   commerceBroker?: CommerceEventBroker;
+  /**
+   * The managed-analytics bridge that emits this document's governed page view into the
+   * commerce broker; defaults to one constructed over the resolved broker. Injectable so
+   * a test can assert the emission without a DOM.
+   */
+  managedAnalyticsBridge?: ManagedAnalyticsEventBrokerBridge;
+  /** Epoch-millisecond source for the page view's correlation expiry; defaults to the wall clock. */
+  now?: () => number;
   /** Host-owned fetch capability for reviewed first-party platform adapters. */
   fetchCapability?: typeof fetch;
   /** Entry import capability; injectable for tests and non-browser hosts. */
@@ -178,6 +201,47 @@ function makeDocumentCommerceBroker(
   });
 }
 
+/**
+ * How long the bootstrap page view's attribution thread stays valid. It matches the
+ * correlation TTL the cart-handoff seam uses, so one visit's page view and any later
+ * commerce event it is threaded to expire together.
+ */
+const PAGE_VIEW_CORRELATION_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * Build this document's bootstrap page-view input from the host document.
+ *
+ * The data allowlist is the whole surface: the route PATH (never the query string, where
+ * preview/candidate wrappers and tokens live) plus attribution already minimized to a
+ * referrer ORIGIN and the five standard UTM tokens. Title, DOM state, and browser globals
+ * are not accepted by this seam and are not read.
+ *
+ * `logicalId` and the correlation id are derived from the plan revision rather than
+ * randomized: one traditional document is counted exactly once, each document load builds
+ * its own broker, and the broker's dedupe key is per-document — so a stable, opaque,
+ * non-identifying value is both sufficient and deterministically testable.
+ */
+function documentPageView(
+  win: LifecycleWindow,
+  descriptor: IntegrationBootDescriptor,
+  now: () => number,
+): ManagedPageViewInput {
+  const attribution = minimizePageAttribution({
+    referrerUrl: win.document?.referrer ?? null,
+    routeUrl: win.location.href,
+  });
+  const id = `pageview-${descriptor.planRevision}`;
+  return {
+    logicalId: id,
+    path: win.location.pathname,
+    correlation: {
+      id,
+      expiresAt: new Date(now() + PAGE_VIEW_CORRELATION_TTL_MS).toISOString(),
+    },
+    ...(attribution ? { attribution } : {}),
+  };
+}
+
 function readDescriptor(win: LifecycleWindow): IntegrationBootDescriptor | null {
   const descriptor = win[INTEGRATION_PLAN_GLOBAL];
   if (!descriptor || typeof descriptor !== "object") return null;
@@ -259,6 +323,9 @@ export function bootIntegrationLifecycle(
   const commerceBroker =
     options.commerceBroker ?? makeDocumentCommerceBroker(descriptor, getConsentSnapshot);
 
+  // The managed-analytics bridge over the SAME broker the adapters subscribe to — the
+  // only seam that emits this document's governed page view. The lifecycle owns when it
+  // fires (after every adapter has subscribed, and re-attempted on a consent grant).
   const lifecycle = new IntegrationLifecycle({
     descriptor,
     loadModule,
@@ -268,6 +335,11 @@ export function bootIntegrationLifecycle(
     environment,
     getConsentSnapshot,
     commerceBroker,
+    managedAnalytics: {
+      bridge: options.managedAnalyticsBridge ??
+        new ManagedAnalyticsEventBrokerBridge({ broker: commerceBroker }),
+      pageView: () => documentPageView(win, descriptor, options.now ?? Date.now),
+    },
   });
   win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
 

package/packages/public-runtime/src/integration/lifecycle-host-asset.d.mts

@@ -0,0 +1,3 @@
+/** Types for the dual-consumer (`.ts` engine + `.mjs` build plugin) host-asset path. */
+export declare const LIFECYCLE_HOST_ASSET_PATH: string;
+export declare const LIFECYCLE_HOST_ASSET_URL: string;

package/packages/public-runtime/src/integration/lifecycle-host-asset.mjs

@@ -0,0 +1,17 @@
+/**
+ * The stable public URL of the document.deferred lifecycle host bundle.
+ *
+ * It lives in a `.mjs` module because it has TWO consumers that cannot share a `.ts`
+ * one: the render engine (`render-phases.ts`) that emits the `<script src>`, and the
+ * build plugin (`apps/storefront/build-plugins/lifecycle-host-asset.mjs`) that produces
+ * the file at that exact path. One source of truth, so the tag and the artifact cannot
+ * disagree — a mismatch would leave every static tenant page with plan data and no host,
+ * which fails silently in exactly the way it is not allowed to.
+ *
+ * The path is version-pinned (`/v1/`) like a platform adapter entry, so a future host
+ * with a different boot contract ships alongside rather than replacing this one.
+ */
+export const LIFECYCLE_HOST_ASSET_PATH = "platform/lifecycle/v1/boot.mjs";
+
+/** The root-absolute, same-origin URL the served markup references. */
+export const LIFECYCLE_HOST_ASSET_URL = `/${LIFECYCLE_HOST_ASSET_PATH}`;

package/packages/public-runtime/src/integration/lifecycle-host-entry.ts

@@ -0,0 +1,16 @@
+/**
+ * The document.deferred lifecycle HOST — the side-effecting entry both document mounts
+ * load, bundled to the stable same-origin URL in `./lifecycle-host-asset.mjs`.
+ *
+ * It is deliberately the whole module: importing it BOOTS. That is what makes it usable
+ * from a plain `<script type="module" src>` tag, which in turn is what lets the raw
+ * marketing mount host the lifecycle at all — it serves a tenant's own document verbatim
+ * and never passes through a bundler, so it cannot host a module-graph import the way
+ * `Layout.astro` can.
+ *
+ * NOT exported from the package barrel: `index.ts` re-exports its modules, and a
+ * self-invoking module there would boot the lifecycle on any server-side import.
+ */
+import { bootIntegrationLifecycleFromDocument } from "./lifecycle-boot.js";
+
+bootIntegrationLifecycleFromDocument();

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

@@ -25,6 +25,8 @@ import type { CommerceEventBroker } from "./commerce-broker.js";
 import type { IntegrationBootDescriptor, BootDescriptorIntegration } from "./render-phases.js";
 import type { NavigationCompletedEvent, NavigationKind } from "./events.js";
 import { validateNavigationCompletedEvent } from "./events.js";
+import type { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
+import type { ManagedPageViewInput } from "./managed-analytics.js";
 import { COMMERCE_EVENT_STOREFRONT_SCHEMA_VERSION, ENVIRONMENT_SCHEMA_VERSION } from "./version.js";
 import type { BrowserEnvironment } from "./environment.js";
 import type { ConsentSnapshot } from "./consent-broker.js";
@@ -125,6 +127,26 @@ export interface IntegrationLifecycleOptions {
    * shape a DOM-free unit test uses when it wires no broker.
    */
   commerceBroker?: CommerceEventBroker;
+  /**
+   * The document's managed-analytics bridge and the bootstrap page-view input for THIS
+   * document. Wiring it is what makes an active analytics adapter actually RECEIVE
+   * something: the bridge is the only seam that emits `storefront.page.viewed.v2` into
+   * {@link commerceBroker}, and an adapter's subscription is receive-only, so with no
+   * bridge every adapter initializes, subscribes, and then waits on a broker nothing
+   * ever emits into.
+   *
+   * The runtime owns the ORDERING, because the broker delivers to the subscribers
+   * registered at emit time and never replays: the bootstrap page view is emitted at the
+   * END of {@link init}, once every eligible integration has initialized (and so
+   * subscribed). `pageView` is a factory rather than a value because it is built from the
+   * host's DOM (path, referrer, UTM), which this DOM-free core must not read itself.
+   *
+   * Absent ⇒ no page view (the shape a DOM-free unit test uses when it wires no bridge).
+   */
+  managedAnalytics?: {
+    bridge: ManagedAnalyticsEventBrokerBridge;
+    pageView: () => ManagedPageViewInput;
+  };
   /** ISO-8601 timestamp source for the navigation event; defaults to wall clock. */
   now?: () => string;
   /** Opaque per-event id source; defaults to a monotonic, non-secret local counter. */
@@ -208,6 +230,34 @@ export class IntegrationLifecycle {
     }
     // A dispose that raced in during an await leaves us terminal; otherwise we are live.
     if (this.state === "initializing") this.state = "initialized";
+    // Last, so every adapter that just subscribed is registered when this emits: the
+    // broker has no replay, so a page view emitted before their `init` reaches nobody.
+    if (this.state === "initialized") this.emitBootstrapPageView();
+  }
+
+  /**
+   * Emit this document's bootstrap-owned page view through the managed-analytics bridge
+   * (`storefront.page.viewed.v2`), exactly once.
+   *
+   * Consent is a PRECONDITION here rather than something the bridge is left to discover:
+   * the bridge counts a document once and is then terminal for `initialize`, so calling
+   * it while `analytics` is ineligible would burn the document's only page view on a
+   * default-deny snapshot and lose it permanently. Instead the attempt is held and
+   * retried from {@link update}, so a visitor who grants analytics after load still gets
+   * counted for the document they are on.
+   *
+   * Analytics never breaks the page: a throwing bridge is swallowed exactly like a
+   * throwing integration.
+   */
+  private emitBootstrapPageView(): void {
+    const managed = this.opts.managedAnalytics;
+    if (!managed || managed.bridge.isInitialized || managed.bridge.isDisposed) return;
+    if (this.opts.commerceBroker?.isConsentEligible("analytics") === false) return;
+    try {
+      managed.bridge.initialize(managed.pageView());
+    } catch {
+      // A page view is never worth a broken document.
+    }
   }
 
   /** Whether the consent gate (when injected) permits loading this integration now. */
@@ -319,6 +369,10 @@ export class IntegrationLifecycle {
         this.observe({ stage: "update", integration, ok: false, reason, error: messageOf(error) });
       }
     }
+    // A consent grant is the case that matters: it both loads a previously-gated adapter
+    // (above) and makes the held-back bootstrap page view emittable, so the document the
+    // visitor consented ON is still counted rather than only its successors.
+    this.emitBootstrapPageView();
   }
 
   /**
@@ -340,6 +394,11 @@ export class IntegrationLifecycle {
     }
     this.active.length = 0;
     this.deferred = []; // gated integrations never loaded — nothing to dispose.
+    try {
+      this.opts.managedAnalytics?.bridge.dispose();
+    } catch {
+      // Teardown is best-effort; a throwing bridge cannot leave the document undisposed.
+    }
     this.state = "disposed";
   }
 

package/packages/public-runtime/src/integration/render-phases.ts

@@ -9,7 +9,9 @@
  * `bodyStart` (body.start fallback), and `bodyDeferred` (document.deferred global
  * entry). Both document mounts — `Layout.astro` and `rawHtmlResponse()` — splice
  * the SAME strings, so their per-phase markup is identical by construction (golden
- * parity is a property of calling one function, not of keeping two in sync).
+ * parity is a property of calling one function, not of keeping two in sync). The
+ * `document.deferred` region includes the lifecycle HOST tag, so "the plan is
+ * published" and "the plan runs" cannot come apart between mounts.
  *
  * Nonce discipline (ADR 0018): the engine stamps the {@link INTEGRATION_NONCE_PLACEHOLDER}
  * sentinel, never a live nonce, onto its inline `<script>`s. The renderer replaces
@@ -37,6 +39,10 @@ import {
   serializeForInlineScript,
 } from "./environment.js";
 import { defaultConsentSnapshot, type ConsentSnapshot } from "./consent-broker.js";
+import { LIFECYCLE_HOST_ASSET_URL } from "./lifecycle-host-asset.mjs";
+
+/** Re-exported so consumers and tests read the host URL from the engine that emits it. */
+export { LIFECYCLE_HOST_ASSET_PATH, LIFECYCLE_HOST_ASSET_URL } from "./lifecycle-host-asset.mjs";
 
 /**
  * The sentinel a renderer stamps in place of a live CSP nonce. It is a valid
@@ -163,11 +169,33 @@ export function renderIntegrationPhases(
     phaseBoundary("body.start") + `<div data-tot-integration-root hidden></div>`;
 
   const bodyDeferred =
-    phaseBoundary("document.deferred") + `<div data-tot-integration-deferred hidden></div>`;
+    phaseBoundary("document.deferred") +
+    `<div data-tot-integration-deferred hidden></div>` +
+    lifecycleHostScript();
 
   return { head, bodyStart, bodyDeferred };
 }
 
+/**
+ * The document.deferred lifecycle HOST tag — what actually boots the plan.
+ *
+ * It belongs to the ENGINE, not to a mount. The engine's promise is that both mounts
+ * emit identical per-phase markup because they call one function; a host installed by
+ * only one of them breaks that promise in the way that matters most, because the mount
+ * that lacks it still publishes `__TOT_INTEGRATION_PLAN__`. A page then advertises a
+ * complete, enabled integration plan and runs none of it — indistinguishable, from every
+ * surface that reports configuration, from a working install.
+ *
+ * Carries no nonce by design: it is a same-origin `src` reference, admitted by
+ * `script-src 'self'` (see `csp.ts`), so it needs neither a nonce nor a content hash —
+ * the same treatment the static `/js/*.js` behaviors get. That also keeps it correct
+ * under the raw mount, which stamps nonces onto the tenant's own inline tags BEFORE
+ * splicing engine bytes.
+ */
+function lifecycleHostScript(): string {
+  return `<script type="module" src="${LIFECYCLE_HOST_ASSET_URL}"></script>`;
+}
+
 /**
  * Replace every {@link INTEGRATION_NONCE_PLACEHOLDER} in `text` (an HTML body or a
  * CSP header value) with one fresh per-response `nonce`. Idempotent on text with no