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

package/packages/public-runtime/src/tenant-assets.ts

@@ -1,5 +1,5 @@
 /**
- * Versioned tenant static-asset store (decision `assets-r2-versioned`).
+ * Versioned tenant static-asset store.
  *
  * Tenant static assets (`tenants/<id>/public/**` — logo, CSS, ~36 binaries) are
  * served from **R2, version-scoped**, replacing the build-time
@@ -275,6 +275,46 @@ export interface IngestResult {
   count: number;
 }
 
+const R2_PUT_MAX_ATTEMPTS = 3;
+const R2_PUT_RETRY_DELAYS_MS = [100, 400] as const;
+
+function errorField(error: unknown, field: string): unknown {
+  if (typeof error !== "object" || error === null || !(field in error)) return undefined;
+  return (error as Record<string, unknown>)[field];
+}
+
+function isTransientR2PutError(error: unknown): boolean {
+  const code = String(errorField(error, "code") ?? "");
+  const status = Number(errorField(error, "status") ?? errorField(error, "statusCode"));
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    code === "10001" ||
+    code === "InternalError" ||
+    (Number.isFinite(status) && status >= 500 && status <= 599) ||
+    /\b10001\b|internal error|temporarily unavailable|service unavailable|timed? out/i.test(message)
+  );
+}
+
+function waitForR2Retry(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function putAssetWithRetry(
+  bucket: R2BucketLike,
+  key: string,
+  bytes: Uint8Array,
+): Promise<void> {
+  for (let attempt = 1; attempt <= R2_PUT_MAX_ATTEMPTS; attempt++) {
+    try {
+      await bucket.put(key, bytes);
+      return;
+    } catch (error) {
+      if (attempt === R2_PUT_MAX_ATTEMPTS || !isTransientR2PutError(error)) throw error;
+      await waitForR2Retry(R2_PUT_RETRY_DELAYS_MS[attempt - 1]!);
+    }
+  }
+}
+
 /**
  * Write a version's public assets to R2 under `tenants/<id>/<versionId>/<rel>`.
  * Content-addressed by the (caller-supplied or computed) snapshot id → immutable
@@ -294,7 +334,9 @@ export async function ingestAssetVersion(
   const keys: string[] = [];
   for (const a of assets) {
     const key = tenantAssetKey(tenantId, vid, a.rel);
-    await bucket.put(key, a.bytes);
+    // The key and bytes are immutable for this version, so retrying an ambiguous
+    // transient R2 failure is idempotent even if the first write landed server-side.
+    await putAssetWithRetry(bucket, key, a.bytes);
     keys.push(key);
   }
   return { versionId: vid, keys, count: keys.length };
@@ -411,6 +453,16 @@ export interface ServeTenantAssetDeps {
   kvGet: (key: string) => Promise<string | null>;
   /** Channel to serve; default "live". Pass `locals.customizationEnv`. */
   channel?: CustomizationEnv;
+  /**
+   * Explicit snapshot versionId that OVERRIDES the channel→version pointer. Set for
+   * a CANDIDATE preview session: a candidate's assets are ingested to R2 keyed by
+   * the candidate versionId but NEVER pointed to by the shared test/live channel
+   * (the no-channel-flip invariant), so without this the candidate's NEW assets are
+   * materialized-but-unreachable. The caller must have authorized the viewer for
+   * THIS tenant (the versionId is a content hash, tenant-scoped by the R2 key) —
+   * see the `/tenants/<id>` route's preview-token check.
+   */
+  versionId?: string;
   /** Request `If-None-Match` header, for conditional GET (304). */
   ifNoneMatch?: string | null;
 }
@@ -434,8 +486,13 @@ export async function serveTenantAsset(
   if (!parsed) return null;
   const { tenantId, rel } = parsed;
 
-  const pointer = await readAssetsPointer({ get: deps.kvGet }, tenantId);
-  const versionId = resolveAssetVersion(pointer, deps.channel ?? "live");
+  // A candidate-preview override pins the snapshot directly; otherwise resolve the
+  // channel→version pointer (live/test) as usual.
+  let versionId = deps.versionId ?? null;
+  if (!versionId) {
+    const pointer = await readAssetsPointer({ get: deps.kvGet }, tenantId);
+    versionId = resolveAssetVersion(pointer, deps.channel ?? "live");
+  }
   if (!versionId) return null; // non-versioned tenant → fall through
 
   const etag = `"${versionId}"`;
@@ -477,3 +534,85 @@ function matchesEtag(ifNoneMatch: string, etag: string): boolean {
     .split(",")
     .some((t) => t.trim() === "*" || norm(t) === target);
 }
+
+// ---------------------------------------------------------------------------
+// Verify — fetch-confirm a version's app-asset subtree actually materialized
+// ---------------------------------------------------------------------------
+
+/** Outcome of {@link verifyMaterializedAssets}. */
+export interface AssetVerificationResult {
+  /** App-asset objects expected to serve at this version. */
+  expected: number;
+  /** How many were confirmed present + non-empty in R2. */
+  verified: number;
+  /** The served relative paths (or artifact paths) that did NOT materialize. */
+  missing: string[];
+  /** Set when the verification itself could not run (fail-closed, not a pass). */
+  error?: string;
+}
+
+/** How many R2 existence probes run at once — matches the runtime's ~6/host reality. */
+const VERIFY_PROBE_POOL = 6;
+
+/**
+ * Confirm every app-asset artifact path is present + non-empty in R2 at
+ * `versionId` — the EXACT object `serveTenantAsset` streams for `/tenants/<id>/<rel>`.
+ * Positive, fail-closed evidence for the version-scoped asset lane: an asset whose
+ * path can't normalize to a served rel, or is absent/empty in R2, is reported
+ * `missing`; a systemic fault (the bucket throwing on every probe) reports the whole
+ * subtree missing with an `error` rather than a vacuous pass. Checking the object at
+ * the published `versionId` (not an HTTP self-fetch) is channel-independent: the
+ * served route may resolve a different channel→version pointer per request, but a
+ * version's bytes are fixed. `bucket` needs only `get`; the body is never read.
+ */
+export async function verifyMaterializedAssets(
+  bucket: Pick<R2BucketLike, "get">,
+  tenantId: string,
+  versionId: string,
+  appAssetArtifactPaths: readonly string[],
+): Promise<AssetVerificationResult> {
+  const expected = appAssetArtifactPaths.length;
+  if (expected === 0) return { expected: 0, verified: 0, missing: [] };
+
+  try {
+    const missing: string[] = [];
+    let verified = 0;
+    let next = 0;
+    const worker = async (): Promise<void> => {
+      while (next < appAssetArtifactPaths.length) {
+        const artifactPath = appAssetArtifactPaths[next++]!;
+        const rel = toPublicRel(tenantId, artifactPath);
+        // An app asset whose path doesn't normalize to a served rel can't serve —
+        // count it missing (fail-closed), labelled by its artifact path.
+        if (!rel) {
+          missing.push(artifactPath);
+          continue;
+        }
+        let present = false;
+        try {
+          const obj = await bucket.get(tenantAssetKey(tenantId, versionId, rel));
+          // Present when the object exists and (when the store reports size) is non-empty.
+          present = obj != null && (obj.size == null || obj.size > 0);
+        } catch {
+          present = false;
+        }
+        if (present) verified++;
+        else missing.push(rel);
+      }
+    };
+    const width = Math.max(1, Math.min(VERIFY_PROBE_POOL, appAssetArtifactPaths.length));
+    await Promise.all(Array.from({ length: width }, worker));
+    // Stable order aids diffing/readability — pool completion order is nondeterministic.
+    missing.sort();
+    return { expected, verified, missing };
+  } catch (err) {
+    // Systemic failure (e.g. the bucket seam throwing on every call): fail closed —
+    // report the whole subtree as unverified rather than claiming a pass.
+    return {
+      expected,
+      verified: 0,
+      missing: [...appAssetArtifactPaths],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/packages/public-runtime/src/tenant.ts

@@ -8,6 +8,7 @@
 import type { ManagedCheckoutConfig } from "./checkout.js";
 import type { CapabilityConfig } from "./capabilities.js";
 import type { AutopilotConfig, MembershipProgramConfig } from "./membership.js";
+import type { IntegrationDeclarationInput } from "./integration/resolve.js";
 
 /**
  * The shared semantic COLOR contract — the widget library's public API.
@@ -65,7 +66,7 @@ export interface ThemeColorTokens {
   /** Hover/active shade of `accent`. Default: a derived darken of `accent`. */
   "accent-hover"?: string;
 
-  // --- Interaction/quality-bar extensions (unit F6). Same "always resolvable"
+  // --- Interaction/quality-bar extensions. Same "always resolvable"
   //     contract: each carries a derived @theme-bridge default so a component may
   //     read it unconditionally; a theme sets one only to brand-tune it. ---
   /** Keyboard focus-ring color (`:focus-visible` outline). Default: `accent`. */
@@ -272,7 +273,7 @@ export interface ComplianceConfig {
 export type SiteType = "commerce" | "marketing";
 
 /**
- * The storefront paywall mode (decision `golive-paywall-storefront-mode-enabled`).
+ * The storefront paywall mode.
  * `"enabled"` is the ONLY value that permits go-live; `"disabled"` (or an absent
  * `storefront.mode`) fails the paywall closed. Kept OPEN as a string union with an
  * `enabled` member so a future billing state (e.g. "trial", "past_due") can be added
@@ -286,7 +287,7 @@ export const STOREFRONT_MODE_ENABLED = "enabled" as const;
 
 /**
  * PURE paywall predicate: does this storefront mode permit go-live? True iff the
- * mode is exactly `"enabled"` (decision `golive-paywall-storefront-mode-enabled`).
+ * mode is exactly `"enabled"`.
  * Generic — takes the mode value, NEVER a domain — so there is no per-store
  * special-case. Undefined/unknown → false (fail-closed).
  */
@@ -390,6 +391,17 @@ export interface TenantConfig {
   siteType?: SiteType;
   /** Explicit feature overrides layered atop the siteType defaults. */
   features?: Partial<TenantFeatures>;
+  /**
+   * Third-party embeds this tenant is allowed to render, as provider slugs from
+   * the platform's `EMBED_PROVIDERS` catalog (e.g. `["pipedrive"]`) — NOT raw
+   * origins. The platform owns each provider's exact CSP origins; listing a slug
+   * here opts the tenant in, and the strict CSP then permits that embed only on
+   * the pages that actually contain it (see `embedCspAdditions`). A provider not
+   * in the catalog needs a reviewed platform addition, not a config edit — so
+   * this stays an auditable allow-list, never an escape hatch to arbitrary hosts.
+   * Declared in the tenant's platform config alongside `siteType`/`capabilities`.
+   */
+  embeds?: string[];
   /** Regulated-commerce affordances; undefined for unregulated tenants. */
   compliance?: ComplianceConfig;
   /**
@@ -431,14 +443,14 @@ export interface TenantConfig {
   commerce?: {
     checkout?: ManagedCheckoutConfig;
     /**
-     * Autopilot (subscription) program visibility (F10). Absent → subscription
+     * Autopilot (subscription) program visibility. Absent → subscription
      * purchase options render wherever a product authors them (framework/dev
      * default). `enabled: false` HIDES Autopilot at launch — the first-class
      * hide-at-launch state for a tenant that isn't selling recurring orders yet.
      */
     autopilot?: AutopilotConfig;
     /**
-     * Membership pricing program (F10): member-vs-list pricing + how a member
+     * Membership pricing program: member-vs-list pricing + how a member
      * discount stacks with a subscription discount. Absent/`enabled:false` → no
      * member pricing renders (the launch default; shopper membership accounts are
      * a Phase-2 managed-checkout capability).
@@ -468,10 +480,20 @@ export interface TenantConfig {
     target: string;
     /** Opt back out without removing the target. Default true when present. */
     enabled?: boolean;
+    /**
+     * Where THIS tenant's LIVE public site actually serves its `live/manifest.json`
+     * — the per-tenant override for the public-site freshness read-back AND the admin
+     * "Live Site" link (see `staticLiveManifestUrl`). Defaults to
+     * `https://<canonicalDomain>/manifest.json` when unset; set it only while a
+     * tenant's live site serves somewhere OTHER than its canonical apex (e.g. a
+     * pre-apex-cutover host). Per-tenant so it never bleeds across stores the way a
+     * single global env override would.
+     */
+    verifyUrl?: string;
   };
   /**
    * Storefront product/subscription state — the paywall the platform gates GO-LIVE
-   * on (decision `golive-paywall-storefront-mode-enabled`). This is the storefront's
+   * on. This is the storefront's
    * analog of the ToT platform SDK's `apiClient.options.storefront.mode`: a per-store
    * PROPERTY set from the merchant's account/subscription, NEVER a per-domain
    * special-case in code. Go-live (the public LIVE publish, `POST /api/changes/accept`)
@@ -495,6 +517,20 @@ export interface TenantConfig {
    * (candidate create/ship/rollback) against a CLONE of a real tenant.
    */
   classification?: "internal-test";
+  /**
+   * Tenant-local browser-integration declarations (ext-kernel-09) — the tenant's
+   * OWN, exact-version integrations (`origin: "tenant-local"`), each a fully
+   * materialized {@link IntegrationDeclarationInput}: the shared browser manifest,
+   * the resolved public config values, and the set of asset paths present for the
+   * declared version. The middleware feeds these to the interim marketing bridge
+   * (`resolveInterimBridgePlan`), which refuses a regulated tenant and otherwise
+   * resolves them into the effective plan the render engine serves — so a declared
+   * unregulated tenant boots its integration on-by-default (consent-gated), and a
+   * tenant with NO declaration is byte-identical to environment-only behavior.
+   * Distinct from `embeds` (opt-in slugs into a platform-owned catalog): this is a
+   * complete self-owned declaration, not a reference into a vetted list.
+   */
+  integrations?: readonly IntegrationDeclarationInput[];
 }
 
 /**
@@ -511,7 +547,7 @@ export function isInternalTestTenant(
 }
 
 // ---------------------------------------------------------------------------
-// Non-premium (self-serve) tenant identity — D4.
+// Non-premium (self-serve) tenant identity.
 //
 // A NEW self-serve / non-premium shop is minted with its identity anchored to a
 // per-tenant subdomain on our own Cloudflare zone: `<label>.tokenoftrust.store`.
@@ -522,7 +558,7 @@ export function isInternalTestTenant(
 // A custom `.com` is layered on LATER as an optional premium alias/upgrade
 // (`rebindPremiumDomain`), never a precondition for a preview.
 //
-// See docs/epics/proposed/invite-gated-auto-build.md §D4.
+// See docs/epics/proposed/invite-gated-auto-build.md.
 // ---------------------------------------------------------------------------
 
 /**
@@ -574,7 +610,7 @@ export function isHostedStoreDomain(domain: string): boolean {
 }
 
 /**
- * Mint the identity for a NEW self-serve / non-premium tenant (D4).
+ * Mint the identity for a NEW self-serve / non-premium tenant.
  *
  * tenant_id == appDomain == canonicalDomain == tot_data_scope ==
  * `<label>.tokenoftrust.store`, with that single hostname as the sole `domains`

package/packages/public-runtime/tests/fixtures/integration/browser-environment.example.json

@@ -0,0 +1,8 @@
+{
+  "$comment": "Public browser-safe example. Missing, malformed, or unknown values must never be treated as live.",
+  "schemaVersion": 1,
+  "siteSurface": "storefront",
+  "environment": "candidate",
+  "canonicalHost": "shop.example.com",
+  "revision": "sha256:example-non-sensitive-render-revision"
+}

package/packages/public-runtime/tests/fixtures/integration/commerce-event.example.json

@@ -0,0 +1,44 @@
+{
+  "$comment": "Architectural browser-event example; contains no customer identity, payment data, signed-cart material, or preview token.",
+  "specversion": "1.0",
+  "id": "01J6EXAMPLE7J6JX18R2X8P4Y5Q",
+  "source": "urn:tokenoftrust:storefront:site-public-example",
+  "type": "storefront.checkout.handoff.v1",
+  "subject": "cart:anonymous-session-item-set",
+  "time": "2026-08-28T20:15:30.000Z",
+  "datacontenttype": "application/json",
+  "dataschema": "https://schemas.tokenoftrust.example/storefront/events/checkout-handoff-v1.json",
+  "storefront": {
+    "schemaVersion": 1,
+    "tenant": "site_public_example",
+    "environment": "staged",
+    "siteSurface": "storefront",
+    "emitter": "browser",
+    "sequence": 7
+  },
+  "correlation": {
+    "id": "corr_public_01J6EXAMPLE",
+    "expiresAt": "2026-08-28T21:15:30.000Z"
+  },
+  "consent": {
+    "schemaVersion": 1,
+    "snapshotId": "consent_public_01J6EXAMPLE",
+    "eligiblePurposes": [
+      "essential",
+      "analytics"
+    ]
+  },
+  "data": {
+    "currency": "USD",
+    "value": "42.50",
+    "itemCount": 2,
+    "items": [
+      {
+        "productId": "product_public_example",
+        "variantId": "variant_public_example",
+        "quantity": 2,
+        "unitPrice": "21.25"
+      }
+    ]
+  }
+}

package/packages/public-runtime/tests/fixtures/integration/commerce-order-event.example.json

@@ -0,0 +1,44 @@
+{
+  "$comment": "Server-authoritative conversion example; emitted from a verified provider webhook, shares the handoff's correlation thread, carries no customer identity or payment data.",
+  "specversion": "1.0",
+  "id": "01J6EXAMPLEORDER9Q2K7M3ZC4T",
+  "source": "urn:tokenoftrust:storefront:site-public-example",
+  "type": "storefront.order.created.v1",
+  "subject": "order:external-public-example",
+  "time": "2026-08-28T20:31:12.000Z",
+  "datacontenttype": "application/json",
+  "dataschema": "https://schemas.tokenoftrust.example/storefront/events/order-created-v1.json",
+  "storefront": {
+    "schemaVersion": 1,
+    "tenant": "site_public_example",
+    "environment": "staged",
+    "siteSurface": "storefront",
+    "emitter": "server"
+  },
+  "correlation": {
+    "id": "corr_public_01J6EXAMPLE",
+    "expiresAt": "2026-08-28T21:15:30.000Z"
+  },
+  "consent": {
+    "schemaVersion": 1,
+    "snapshotId": "consent_public_01J6EXAMPLE",
+    "eligiblePurposes": [
+      "essential",
+      "analytics"
+    ]
+  },
+  "data": {
+    "orderId": "order_public_example",
+    "currency": "USD",
+    "value": "42.50",
+    "itemCount": 2,
+    "items": [
+      {
+        "productId": "product_public_example",
+        "variantId": "variant_public_example",
+        "quantity": 2,
+        "unitPrice": "21.25"
+      }
+    ]
+  }
+}

package/packages/public-runtime/tests/fixtures/integration/compliance-assurance-record.example.json

@@ -0,0 +1,50 @@
+{
+  "$comment": "Architectural audit example; not an authorization token or approved production schema.",
+  "schemaVersion": 1,
+  "recordId": "assurance_public_01J6EXAMPLE",
+  "tenantPublicId": "site_public_example",
+  "environment": "live",
+  "surface": "unregulated-marketing",
+  "classification": "elevated-supported",
+  "integration": {
+    "appId": "com.example.analytics-adapter",
+    "version": "2.1.0",
+    "digest": "sha256:example-immutable-package-digest",
+    "executionTier": "elevated-parent"
+  },
+  "declaredEffects": {
+    "capabilities": [
+      "parent-document.full",
+      "events.page-and-cart.anonymous"
+    ],
+    "consentPurposes": [
+      "analytics"
+    ],
+    "cspOrigins": [
+      "https://cdn.analytics.example",
+      "https://collect.analytics.example",
+      "https://pixel.analytics.example"
+    ],
+    "dataClasses": [
+      "public-catalog",
+      "anonymous-cart-summary"
+    ]
+  },
+  "compliance": {
+    "regulatedSharedRuntimeWaiver": false,
+    "configuredObligations": [],
+    "eligibleForOutsideGuarantee": true,
+    "protectedSurfaceEvidence": "evidence://candidate/example-assurance-proof"
+  },
+  "acknowledgement": {
+    "actorId": "operator_public_example",
+    "actorRole": "tenant-owner",
+    "reason": "Approved analytics integration after candidate privacy, performance, and CSP review.",
+    "recordedAt": "2026-08-28T20:30:00.000Z",
+    "expiresAt": "2027-02-28T20:30:00.000Z"
+  },
+  "rollback": {
+    "knownGoodVersion": "2.0.3",
+    "knownGoodRevision": "sha256:example-known-good-revision"
+  }
+}

package/packages/public-runtime/tests/fixtures/integration/integration-manifest-v2.example.json

@@ -0,0 +1,120 @@
+{
+  "$comment": "Architectural example only; field names and schema URI are not approved production contracts.",
+  "$schema": "https://schemas.tokenoftrust.example/storefront/integration-manifest-v2.schema.json",
+  "schemaVersion": 2,
+  "app": {
+    "id": "com.example.analytics-adapter",
+    "name": "Example Analytics Adapter",
+    "version": "2.1.0",
+    "digest": "sha256:example-immutable-package-digest",
+    "publisher": "Example Vendor",
+    "supportUrl": "https://support.example.invalid/storefront"
+  },
+  "compatibility": {
+    "storefrontBrowserContract": ">=2.0.0 <3.0.0",
+    "configurationSchemaVersion": 3
+  },
+  "browser": {
+    "executionTier": "elevated-parent",
+    "entry": {
+      "asset": "public/apps/example-analytics/entry.v2.1.0.js",
+      "format": "module",
+      "phase": "document.deferred"
+    },
+    "contributions": [
+      {
+        "id": "consent-defaults",
+        "phase": "consent.defaults",
+        "kind": "platform-template",
+        "template": "consent-defaults.v1"
+      },
+      {
+        "id": "fallback-markup",
+        "phase": "body.start",
+        "kind": "platform-template",
+        "template": "vendor-fallback-frame.v1"
+      }
+    ],
+    "dependencies": [
+      {
+        "contribution": "entry",
+        "after": "consent-defaults"
+      }
+    ],
+    "publicConfigSchema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "destinationId"
+      ],
+      "properties": {
+        "destinationId": {
+          "type": "string",
+          "pattern": "^[A-Z0-9_-]{3,64}$",
+          "description": "Public vendor destination identifier; never a credential."
+        },
+        "debugInNonLive": {
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
+    "consent": {
+      "purposes": [
+        "analytics"
+      ],
+      "loadWhen": "all-declared-purposes-eligible",
+      "unknownState": "block"
+    },
+    "csp": {
+      "profiles": [],
+      "sources": {
+        "script-src": [
+          "https://cdn.analytics.example"
+        ],
+        "connect-src": [
+          "https://collect.analytics.example"
+        ],
+        "frame-src": [],
+        "img-src": [
+          "https://pixel.analytics.example"
+        ],
+        "style-src": []
+      }
+    },
+    "permissions": {
+      "events": [
+        "storefront.page.viewed.v1",
+        "storefront.product.viewed.v1",
+        "storefront.cart.updated.v1"
+      ],
+      "data": [
+        "catalog.product.public",
+        "cart.summary.anonymous"
+      ],
+      "actions": [],
+      "domIntent": "full-parent-authority-review-metadata-only"
+    },
+    "performanceBudget": {
+      "maxTransferredBytes": 75000,
+      "maxAdditionalRequests": 4,
+      "maxMainThreadMilliseconds": 50,
+      "mustBeAsyncOrDeferred": true
+    }
+  },
+  "server": {
+    "topics": [],
+    "secretRequirements": []
+  },
+  "assurance": {
+    "requestedClassification": "elevated-supported",
+    "regulatedTenantDefault": "disabled-until-certified"
+  },
+  "configurationMigrations": [
+    {
+      "from": 2,
+      "to": 3,
+      "migration": "migrations/public-config-2-to-3.v1.json"
+    }
+  ]
+}

package/packages/public-runtime/tests/fixtures/integration/managed-analytics-v1/fake-adapter-catalog.json

@@ -0,0 +1,35 @@
+{
+  "apiVersion": "v1",
+  "requestId": "req_fake_catalog_1",
+  "data": {
+    "items": [
+      {
+        "schemaVersion": 1,
+        "adapterId": "fake.metrics",
+        "adapterVersion": "1.0.0",
+        "displayName": "Fake Metrics",
+        "description": "A deterministic fake catalog adapter for consumers and tests.",
+        "availability": "available",
+        "configuration": [
+          {
+            "key": "datasetId",
+            "label": "Dataset id",
+            "description": "Public identifier for the fake dataset.",
+            "kind": "string",
+            "required": true
+          },
+          {
+            "key": "sampleRate",
+            "label": "Sample rate",
+            "description": "Integer sampling percentage.",
+            "kind": "integer",
+            "required": false
+          }
+        ],
+        "eventTypes": ["storefront.page.viewed.v1"],
+        "consentPurposes": ["analytics"],
+        "collectionOrigins": ["https://collector.invalid"]
+      }
+    ]
+  }
+}

package/packages/public-runtime/tests/fixtures/integration/tenant-action-registry.example.json

@@ -0,0 +1,11 @@
+{
+  "$comment": "Canonical v1 action names are explicit authored data and are never inferred from markup or labels.",
+  "schemaVersion": 1,
+  "actions": [
+    { "name": "user_clicked_contact_sales_mktg" },
+    { "name": "user_clicked_create_account_mktg" },
+    { "name": "user_clicked_login_mktg" },
+    { "name": "user_clicked_contact_support_consumer_mktg" },
+    { "name": "user_clicked_contact_support_partner_mktg" }
+  ]
+}

package/packages/public-runtime/tests/fixtures/integration/tenant-local-example/README.md

@@ -0,0 +1,22 @@
+# Tenant-local example integration
+
+The smallest complete, valid tenant-local integration declaration: one
+`document.deferred` entry module plus one `body.start` fallback contribution,
+gated on the `analytics` consent purpose and the curated `plausible` CSP
+profile. It validates through `validateIntegrationManifest` — the identical
+function a managed app's manifest validates through (ADR 0014 C1) — so
+nothing here is a tenant-local special case.
+
+| File | What it is |
+|---|---|
+| `manifest.json` | The `IntegrationManifest` — the same contract a managed app ships. |
+| `public-config.json` | Resolved tenant values for `manifest.json`'s `browser.publicConfigSchema`. |
+| `entry.js` | The `document.deferred` entry module (`IntegrationLifecycleModule`: `init`/`update`/`dispose`). |
+
+Walked end to end — validate → resolve → render → boot → update → dispose →
+remove — by
+[`../../../integration/kernel-docs-harness.test.ts`](../../../integration/kernel-docs-harness.test.ts).
+Run it with `pnpm --filter @tot/public-runtime test kernel-docs-harness`.
+
+Full contract reference, ordering/failure guide, and removal walkthrough:
+[`docs/architecture/browser-integration-kernel.md`](../../../../../../docs/architecture/browser-integration-kernel.md).