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

package/apps/storefront/src/lib/apps/registryService.ts

@@ -34,9 +34,42 @@
  *     (no detail that would let a caller distinguish "wrong tenant" from
  *     "never existed"); a suspended/uninstalled install rejects further
  *     mutation with `invalid_state`.
+ *
+ * Version retention + the single source-of-truth (ext-apps-02b): every
+ * activation — `install`, `update`, and `rollback` — retains the version's
+ * COMPLETE restorable facet set through {@link AppVersionStore} (its
+ * `app_version_snapshots` table over the SAME `Queryable` seam this service
+ * uses). The authority for "which version is active" is the version store's
+ * `MAX(seq)` current snapshot; `app_installs.app_version` is a DERIVED MIRROR
+ * that this service re-points from the store's post-write current version in
+ * the same operation ({@link AppRegistryService.syncActiveVersionMirror}). The
+ * two can never diverge because the mirror is only ever written from the
+ * store's current snapshot — you change the active version by retaining/rolling
+ * one, never by writing the mirror directly. `rollback` restores a prior
+ * version's whole facet set atomically (store-side) and re-syncs the mirror, so
+ * the registry's active version always agrees with the restored snapshot.
  */
 import { validateScopes, type ScopeDenial } from "./scopes.js";
 import { validateWebhookEndpoint } from "../webhooks/endpointGuard.js";
+import {
+  AppVersionStore,
+  AppVersionError,
+  type AppVersionFacets,
+  type AppVersionSnapshot,
+} from "./appVersionStore.js";
+import {
+  DEFAULT_EXECUTION_TIER,
+  EXECUTION_TIERS,
+  ENTRY_FORMATS,
+  VENDOR_ADDRESSABLE_PHASES,
+  CONSENT_LOAD_WHEN,
+  type ExecutionTier,
+  type EntryFormat,
+  type ReservedPhase,
+  type ConsentLoadWhen,
+  type PlanIntegrationEntry,
+  type PlanIntegrationConsent,
+} from "@tot/public-runtime";
 import type { Queryable } from "../d1/catalog.js";
 
 export type AppInstallStatus = "active" | "suspended" | "uninstalled";
@@ -65,7 +98,8 @@ export type AppAuditEvent =
   | "suspended"
   | "resumed"
   | "uninstalled"
-  | "credentials_rotated";
+  | "credentials_rotated"
+  | "rolled_back";
 
 /** The auth-derived context every install is scoped to — never caller input. */
 export interface InstallActorContext {
@@ -81,6 +115,14 @@ export interface InstallInput {
   manifest: unknown;
   webhookEndpoint?: string | null;
   widgetPlacements?: unknown[];
+  /**
+   * The fully plan-resolved facet set to retain for this version. Optional: when
+   * a caller has already run the plan resolver (ext-kernel-03) it passes the
+   * resolved set and it is snapshotted verbatim; when absent the registry
+   * projects a restorable facet set from the captured manifest + granted scopes
+   * ({@link resolveVersionFacets}). Either way `install` ALWAYS retains a v1.
+   */
+  versionFacets?: AppVersionFacets;
 }
 
 export interface AppInstallPatch {
@@ -89,6 +131,8 @@ export interface AppInstallPatch {
   manifest?: unknown;
   webhookEndpoint?: string | null;
   widgetPlacements?: unknown[];
+  /** As {@link InstallInput.versionFacets}: the resolved set to retain for this activation. */
+  versionFacets?: AppVersionFacets;
 }
 
 export type RegistryErrorCode =
@@ -97,7 +141,9 @@ export type RegistryErrorCode =
   | "already_installed"
   | "invalid_state"
   | "invalid_webhook_endpoint"
-  | "invalid_widget_placement";
+  | "invalid_widget_placement"
+  | "unknown_version"
+  | "invalid_version_facets";
 
 /**
  * `install()`'s return: the install row PLUS the one-time client credential
@@ -257,12 +303,100 @@ function toDomain(row: AppInstallRow): AppInstall {
   };
 }
 
+/**
+ * Project the version's restorable facet set from what the registry
+ * authoritatively holds. A pre-resolved `override` (produced upstream by the
+ * plan resolver) is snapshotted verbatim EXCEPT for the two facets the registry
+ * — not the resolver — is the authority for: the version handle (`appVersion`)
+ * and the granted `scopes`. With no override, the set is projected from the
+ * captured `manifest`'s declared browser facets (tier / digest / entry /
+ * consent) with fail-closed defaults for a partial declaration; the
+ * cross-cutting `contributions` / `cspOrigins` / tenant `publicConfig` a full
+ * plan resolution computes are left empty here and only ever arrive through the
+ * `override`. Pure — no I/O, never throws (the version store re-scans the result
+ * for secret material before it is persisted).
+ */
+export function resolveVersionFacets(args: {
+  appVersion: string;
+  scopes: string[];
+  manifest: unknown;
+  override?: AppVersionFacets;
+}): AppVersionFacets {
+  const { appVersion, scopes, manifest, override } = args;
+  if (override) return { ...override, appVersion, scopes };
+
+  const browser = asObject(asObject(manifest)?.["browser"]);
+  return {
+    appVersion,
+    digest: readString(asObject(asObject(manifest)?.["app"])?.["digest"]) ?? "",
+    executionTier: readExecutionTier(browser?.["executionTier"]),
+    entry: readEntry(asObject(browser?.["entry"])),
+    publicConfig: {},
+    contributions: [],
+    scopes,
+    consent: readConsent(asObject(browser?.["consent"])),
+    cspOrigins: [],
+  };
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readExecutionTier(value: unknown): ExecutionTier {
+  return typeof value === "string" && (EXECUTION_TIERS as readonly string[]).includes(value)
+    ? (value as ExecutionTier)
+    : DEFAULT_EXECUTION_TIER;
+}
+
+function readEntry(entry: Record<string, unknown> | undefined): PlanIntegrationEntry {
+  const url = readString(entry?.["asset"]) ?? "";
+  const format =
+    typeof entry?.["format"] === "string" && (ENTRY_FORMATS as readonly string[]).includes(entry["format"] as string)
+      ? (entry["format"] as EntryFormat)
+      : "module";
+  const phase =
+    typeof entry?.["phase"] === "string" &&
+    (VENDOR_ADDRESSABLE_PHASES as readonly string[]).includes(entry["phase"] as string)
+      ? (entry["phase"] as ReservedPhase)
+      : "document.deferred";
+  return { url, format, phase };
+}
+
+function readConsent(consent: Record<string, unknown> | undefined): PlanIntegrationConsent {
+  const purposes = Array.isArray(consent?.["purposes"])
+    ? (consent["purposes"] as unknown[]).filter((p): p is string => typeof p === "string")
+    : [];
+  const loadWhen: ConsentLoadWhen =
+    typeof consent?.["loadWhen"] === "string" &&
+    (CONSENT_LOAD_WHEN as readonly string[]).includes(consent["loadWhen"] as string)
+      ? (consent["loadWhen"] as ConsentLoadWhen)
+      : "essential-only";
+  return { purposes, loadWhen };
+}
+
 export class AppRegistryService {
+  private readonly versionStore: AppVersionStore;
+
   constructor(
     private readonly db: Queryable,
     private readonly credentials: CredentialPort,
     private readonly now: () => string = () => new Date().toISOString(),
-  ) {}
+    /**
+     * The version-retention spine. Defaults to one over the SAME `Queryable`
+     * seam + clock, so retention writes share this service's transaction shape;
+     * injectable for tests.
+     */
+    versionStore: AppVersionStore = new AppVersionStore(db, now),
+  ) {
+    this.versionStore = versionStore;
+  }
 
   /**
    * Install an app for one (tenant, env). Validates scopes BEFORE writing
@@ -291,6 +425,16 @@ export class AppRegistryService {
       );
     }
 
+    // The active version is whatever we retain below; `app_installs.app_version`
+    // is a mirror of it. Resolve the facet set FIRST so the row's `app_version`
+    // is the same version handle the retained v1 snapshot carries.
+    const facets = resolveVersionFacets({
+      appVersion: input.appVersion,
+      scopes: validation.scopes,
+      manifest: input.manifest,
+      override: input.versionFacets,
+    });
+
     const installId = crypto.randomUUID();
     const now = this.now();
     await this.db.run(
@@ -300,7 +444,7 @@ export class AppRegistryService {
        VALUES (?,?,?,?,?,'active',?,?,?,?,?,?,?)`,
       installId,
       input.appId,
-      input.appVersion,
+      facets.appVersion,
       ctx.tenantId,
       input.env,
       JSON.stringify(validation.scopes),
@@ -323,12 +467,30 @@ export class AppRegistryService {
       await this.db.run(`DELETE FROM app_installs WHERE install_id = ?`, installId);
       throw cause;
     }
+
+    // Retain v1's complete facet set. Fail-closed: a facet set naming secret
+    // material (or any retention failure) unwinds the whole install — clear the
+    // just-issued credential and delete the row — so a refused install leaves no
+    // trace, exactly like the credential-failure path above.
+    try {
+      await this.versionStore.retainVersion({
+        installId,
+        tenantId: ctx.tenantId,
+        facets,
+        actor: ctx.actor,
+      });
+    } catch (cause) {
+      await this.credentials.clear(installId).catch(() => {});
+      await this.db.run(`DELETE FROM app_installs WHERE install_id = ?`, installId);
+      throw this.asRegistryError(cause);
+    }
+
     await this.appendAudit({
       installId,
       tenantId: ctx.tenantId,
       event: "installed",
       actor: ctx.actor,
-      detail: { appId: input.appId, appVersion: input.appVersion, env: input.env },
+      detail: { appId: input.appId, appVersion: facets.appVersion, env: input.env },
     });
 
     return {
@@ -340,7 +502,7 @@ export class AppRegistryService {
   /** Read one install by id, or `null` if it doesn't exist. */
   async get(installId: string): Promise<AppInstall | null> {
     const row = await this.db.first<AppInstallRow>(
-      `SELECT * FROM app_installs WHERE install_id = ?`,
+      `SELECT * FROM app_installs WHERE install_id = ? AND managed_kind IS NULL`,
       installId,
     );
     return row ? toDomain(row) : null;
@@ -349,7 +511,7 @@ export class AppRegistryService {
   /** All installs for a tenant, newest first. */
   async listByTenant(tenantId: string): Promise<AppInstall[]> {
     const rows = await this.db.all<AppInstallRow>(
-      `SELECT * FROM app_installs WHERE tenant_id = ? ORDER BY created_at DESC`,
+      `SELECT * FROM app_installs WHERE tenant_id = ? AND managed_kind IS NULL ORDER BY created_at DESC`,
       tenantId,
     );
     return rows.map(toDomain);
@@ -396,12 +558,34 @@ export class AppRegistryService {
     const widgetPlacementsJson =
       widgetPlacements !== undefined ? JSON.stringify(widgetPlacements) : row.widget_placements;
 
+    // Retain this update as a new activation BEFORE the metadata write — after
+    // every fail-closed validation above, so a bad patch retains nothing. This
+    // captures the whole facet set at this version and, being the last write
+    // gate that can refuse (a secret-bearing facet set), keeps `update` all-or-
+    // nothing. `app_version` is NOT written here: it is the mirror, re-pointed
+    // below from the store's post-retain current version.
+    const facets = resolveVersionFacets({
+      appVersion,
+      scopes: effectiveScopes,
+      manifest: patch.manifest !== undefined ? patch.manifest : (JSON.parse(row.manifest) as unknown),
+      override: patch.versionFacets,
+    });
+    try {
+      await this.versionStore.retainVersion({
+        installId,
+        tenantId: row.tenant_id,
+        facets,
+        actor,
+      });
+    } catch (cause) {
+      throw this.asRegistryError(cause);
+    }
+
     await this.db.run(
       `UPDATE app_installs
-          SET app_version = ?, scopes = ?, manifest = ?, webhook_endpoint = ?,
+          SET scopes = ?, manifest = ?, webhook_endpoint = ?,
               widget_placements = ?, updated_at = ?
         WHERE install_id = ?`,
-      appVersion,
       scopesJson,
       manifestJson,
       webhookEndpoint,
@@ -409,6 +593,7 @@ export class AppRegistryService {
       now,
       installId,
     );
+    await this.syncActiveVersionMirror(installId);
 
     await this.appendAudit({
       installId,
@@ -421,6 +606,37 @@ export class AppRegistryService {
     return this.getOrThrow(installId);
   }
 
+  /**
+   * Roll an install back to a retained version, restoring its COMPLETE facet set
+   * atomically through {@link AppVersionStore.rollbackTo} (forward-only: a new
+   * activation copying the target's facets verbatim), then re-point the
+   * `app_installs.app_version` mirror to the restored version so the registry's
+   * active version agrees with the store's current snapshot. Rejects an
+   * uninstalled install (a dead install can't be mutated) and an unretained
+   * `toSeq` (`unknown_version`), leaving the store untouched in both cases.
+   */
+  async rollback(installId: string, toSeq: number, actor: string): Promise<AppInstall> {
+    const row = await this.mustFindRow(installId);
+    if (row.status === "uninstalled") {
+      throw new RegistryError(`Cannot roll back an uninstalled app.`, "invalid_state");
+    }
+    let restored: AppVersionSnapshot;
+    try {
+      restored = await this.versionStore.rollbackTo({ installId, toSeq, actor });
+    } catch (cause) {
+      throw this.asRegistryError(cause);
+    }
+    await this.syncActiveVersionMirror(installId);
+    await this.appendAudit({
+      installId,
+      tenantId: row.tenant_id,
+      event: "rolled_back",
+      actor,
+      detail: { toSeq, restoredVersion: restored.appVersion, activationSeq: restored.seq },
+    });
+    return this.getOrThrow(installId);
+  }
+
   /** Suspend an active install: disables API/webhook/widget access. */
   async suspend(installId: string, actor: string): Promise<AppInstall> {
     const row = await this.mustFindRow(installId);
@@ -519,6 +735,40 @@ export class AppRegistryService {
     return validation.placements;
   }
 
+  /**
+   * Re-point `app_installs.app_version` (the derived mirror) to the version
+   * store's current (`MAX(seq)`) snapshot — the single reconciliation step that
+   * keeps the mirror and the source-of-truth authority from diverging. Called
+   * after every store write that can change the active version (`update`,
+   * `rollback`); `install` sets the mirror from the same resolved facet set at
+   * INSERT time, so it is already consistent there.
+   */
+  private async syncActiveVersionMirror(installId: string): Promise<void> {
+    const current = await this.versionStore.currentVersion(installId);
+    if (!current) return;
+    await this.db.run(
+      `UPDATE app_installs SET app_version = ?, updated_at = ? WHERE install_id = ?`,
+      current.appVersion,
+      this.now(),
+      installId,
+    );
+  }
+
+  /**
+   * Translate a version-store {@link AppVersionError} into this service's
+   * `RegistryError` vocabulary so callers branch on one `.code` space: an
+   * unretained rollback target → `unknown_version`, a secret-bearing/invalid
+   * facet set → `invalid_version_facets`. Anything else rethrows unchanged.
+   */
+  private asRegistryError(cause: unknown): unknown {
+    if (cause instanceof AppVersionError) {
+      const code: RegistryErrorCode =
+        cause.code === "unknown_target" ? "unknown_version" : "invalid_version_facets";
+      return new RegistryError(cause.message, code);
+    }
+    return cause;
+  }
+
   private async setStatus(installId: string, status: AppInstallStatus): Promise<void> {
     await this.db.run(
       `UPDATE app_installs SET status = ?, updated_at = ? WHERE install_id = ?`,
@@ -544,7 +794,11 @@ export class AppRegistryService {
   /** Fetch a row or throw the generic fail-closed `not_found` — no enumeration detail. */
   private async mustFindRow(installId: string): Promise<AppInstallRow> {
     const row = await this.db.first<AppInstallRow>(
-      `SELECT * FROM app_installs WHERE install_id = ?`,
+      // Managed-analytics installs have a reviewed-first lifecycle and are owned
+      // exclusively by ManagedAnalyticsApiV1Facade. Hiding them here fences the
+      // legacy registry's update/status/rollback/uninstall methods from racing
+      // the managed CAS or appending an activation behind its revision counter.
+      `SELECT * FROM app_installs WHERE install_id = ? AND managed_kind IS NULL`,
       installId,
     );
     if (!row) throw new RegistryError(`App install not found.`, "not_found");

package/apps/storefront/src/lib/apps/tenantIntegrationMaterialization.ts

@@ -0,0 +1,170 @@
+/**
+ * Control-plane materialization of a tenant's OWN (`tenant-local`) integration
+ * declarations for the admin seams (ext-kernel-09).
+ *
+ * The middleware materializes these same declarations on the render hot path; this
+ * module materializes them for the ADMIN plane — the ext-admin-02 read model and the
+ * ext-admin-07 lifecycle route — so a declared integration shows its REAL effective
+ * state (its resolved plan, compiled CSP, consent needs) instead of a null /
+ * `not_materialized` placeholder. Resolution runs through the SAME interim marketing
+ * bridge the render path uses, so a regulated tenant is refused identically (no
+ * effective plan → the declaration surfaces honestly as unmaterialized) and an
+ * eligible unregulated one resolves the exact plan it serves.
+ *
+ * A tenant-local declaration is a live-by-config integration (on-by-default), not a
+ * candidate under review: its effective state is what the read model shows and what
+ * the lifecycle route loads. It has no separate promotion gate — publishing an
+ * on-by-default declaration would change nothing — so the lifecycle route surfaces
+ * its live state and refuses a preview/publish with no candidate rather than
+ * fabricating one.
+ */
+import { loadTenantIntegrationDeclarations } from "@/lib/integration/tenantDeclarations";
+import {
+  resolveInterimBridgePlan,
+  compileIntegrationCspFromPlan,
+  collectDeclaredCspProfiles,
+  buildCandidateEvidence,
+  defaultConsentSnapshot,
+  ENVIRONMENT_SCHEMA_VERSION,
+  type TenantConfig,
+  type BrowserEnvironment,
+  type IntegrationEnvironment,
+  type IntegrationSiteSurface,
+  type EffectivePlan,
+  type CompiledIntegrationCsp,
+  type ConsentSnapshot,
+  type AssetVerificationResult,
+} from "@tot/public-runtime";
+import type { IntegrationReadModelInputItem } from "@/lib/apps/integrationReadModel.js";
+import {
+  facetsFromEvidence,
+  initialLifecycleState,
+  type TenantIntegrationLifecycleState,
+} from "@/lib/apps/integrationLifecycle.js";
+
+/** Stable, synthetic install id for a tenant-local declaration (no registry install backs it). */
+export function tenantLocalInstallId(appId: string): string {
+  return `tenant-local:${appId}`;
+}
+
+/** A same-origin (public/-committed) entry declares no R2 app assets — a clean zero verify. */
+const NO_R2_APP_ASSETS: AssetVerificationResult = { expected: 0, verified: 0, missing: [] };
+
+/** The admin-plane browser environment for a lifecycle stage — the `admin` surface. */
+function adminEnvironment(tenant: TenantConfig, stage: IntegrationEnvironment): BrowserEnvironment {
+  const surface: IntegrationSiteSurface = "admin";
+  return {
+    schemaVersion: ENVIRONMENT_SCHEMA_VERSION,
+    siteSurface: surface,
+    environment: stage,
+    canonicalHost: tenant.canonicalDomain || tenant.tenant_id,
+    revision: `admin-${stage}`,
+  };
+}
+
+/** The resolved plan + compiled CSP + consent snapshot for a tenant's tenant-local declarations. */
+export interface MaterializedTenantLocalPlan {
+  plan: EffectivePlan;
+  compiledCsp: CompiledIntegrationCsp;
+  consentSnapshot: ConsentSnapshot;
+}
+
+/**
+ * Resolve a tenant's tenant-local declarations into the effective plan + compiled CSP
+ * for `stage`, through the interim bridge. Null when the tenant declares none, the
+ * bridge refuses (regulated), or the plan/CSP fail closed — every "no effective state"
+ * case an honest null, never a partial plan.
+ */
+export function materializeTenantLocalPlan(
+  tenant: TenantConfig,
+  stage: IntegrationEnvironment,
+): MaterializedTenantLocalPlan | null {
+  const declarations = loadTenantIntegrationDeclarations(tenant);
+  if (declarations.length === 0) return null;
+  const bridge = resolveInterimBridgePlan({
+    tenantPublicId: tenant.tenant_id,
+    tenant,
+    environment: adminEnvironment(tenant, stage),
+    declarations,
+  });
+  if (!bridge.ok) return null;
+  const compiled = compileIntegrationCspFromPlan(
+    bridge.plan,
+    collectDeclaredCspProfiles(declarations),
+  );
+  if (!compiled.ok) return null;
+  return { plan: bridge.plan, compiledCsp: compiled.value, consentSnapshot: defaultConsentSnapshot() };
+}
+
+/**
+ * Build the ext-admin-02 read-model input items for a tenant's tenant-local
+ * declarations. Each carries the resolved effective plan + compiled CSP so the
+ * assembler surfaces REAL effective state; a refused/failed resolution yields a null
+ * effective plan, so the declaration surfaces as honestly unmaterialized (never a
+ * fabricated live state).
+ */
+export function tenantLocalReadModelItems(
+  tenant: TenantConfig,
+  stage: IntegrationEnvironment,
+): IntegrationReadModelInputItem[] {
+  const declarations = loadTenantIntegrationDeclarations(tenant);
+  if (declarations.length === 0) return [];
+  const materialized = materializeTenantLocalPlan(tenant, stage);
+  return declarations.map((decl) => {
+    const { app } = decl.manifest;
+    return {
+      install: {
+        installId: tenantLocalInstallId(app.id),
+        appId: app.id,
+        appVersion: app.version,
+        tenantId: tenant.tenant_id,
+        status: "active",
+      },
+      purpose: app.name,
+      desiredConfig: decl.publicConfig,
+      effectivePlan: materialized?.plan ?? null,
+      effectiveCsp: materialized?.compiledCsp ?? null,
+      consentSnapshot: materialized?.consentSnapshot ?? null,
+    };
+  });
+}
+
+/**
+ * Load the real lifecycle state for a tenant-local declared install — a live-by-config
+ * integration whose effective plan occupies the resolved stage slot. Null when the
+ * install id names no materialized tenant-local declaration for the tenant (so the
+ * lifecycle route answers a fail-closed 409, never a fabricated state).
+ */
+export function loadTenantLocalLifecycleState(
+  tenant: TenantConfig,
+  installId: string,
+  stage: IntegrationEnvironment,
+): TenantIntegrationLifecycleState | null {
+  const declarations = loadTenantIntegrationDeclarations(tenant);
+  const decl = declarations.find((d) => tenantLocalInstallId(d.manifest.app.id) === installId);
+  if (!decl) return null;
+  const materialized = materializeTenantLocalPlan(tenant, stage);
+  if (!materialized) return null;
+
+  const appId = decl.manifest.app.id;
+  const evidence = buildCandidateEvidence({
+    plan: materialized.plan,
+    compiledCsp: materialized.compiledCsp,
+    assets: NO_R2_APP_ASSETS,
+  });
+  if (!evidence.ok) return null;
+  const facets = facetsFromEvidence(evidence.value, appId);
+
+  const state = initialLifecycleState({
+    tenantPublicId: tenant.tenant_id,
+    installId,
+    appId,
+  });
+  // A tenant-local declaration is live-by-config: its resolved plan IS the serving
+  // (live) facet, and it is its own known-good rollback target.
+  return {
+    ...state,
+    stages: { ...state.stages, live: facets },
+    knownGood: [facets],
+  };
+}

package/apps/storefront/src/lib/apps/v84CleanCloneReplayContext.ts

@@ -0,0 +1,16 @@
+/** Shared fake/local state contract for one composed v84 clean-clone pass. */
+export const V84_REPLAY_SESSION_ID = "offline-v84-shared-clone-session" as const;
+export const V84_REPLAY_CLONE_TENANT = "tokenoftrust.com~clone~gtm-migration-v84" as const;
+
+export interface V84CleanCloneReplayContext {
+  readonly sessionId: typeof V84_REPLAY_SESSION_ID;
+  readonly cloneTenant: typeof V84_REPLAY_CLONE_TENANT;
+  read<T>(key: string): T | undefined;
+  write(key: string, value: unknown): void;
+  delete(key: string): void;
+  keys(prefix?: string): readonly string[];
+}
+
+export function sameV84ReplayValue(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}

package/apps/storefront/src/lib/apps/v84CloneLifecycleCacheEvidence.ts

@@ -0,0 +1,105 @@
+/** Clone-only cold/warm cache evidence over local managed-install state. */
+import { getCachedPage, pageCacheKey, putCachedPage } from "../edgeCache.js";
+import type { V84DisabledInstallMaterializationResult } from "./v84CloneLifecycleMaterialization.js";
+import {
+  V84_NATIVE_CLONE_TENANT,
+  V84_NATIVE_SOURCE_TENANT,
+} from "./v84CloneNativeInstallEvidence.js";
+import type { V84CleanCloneReplayContext } from "./v84CleanCloneReplayContext.js";
+
+const CACHE_BODY = "<!-- offline v84 lifecycle cache artifact; no integration markup -->";
+const INTEGRATION_MARKUP = /<script|dataLayer|googletagmanager|GTM-|\beval\s*\(/i;
+
+function fakeCache(replayContext?: V84CleanCloneReplayContext) {
+  const store = new Map<string, Response>();
+  const reads: string[] = [];
+  const writes: string[] = [];
+  const cache = {
+    async match(request: Request) {
+      reads.push(request.url);
+      if (replayContext) {
+        const found = replayContext.read<{
+          body: string;
+          headers: Record<string, string>;
+          status: number;
+        }>(`stage/lifecycle/cache/${encodeURIComponent(request.url)}`);
+        return found ? new Response(found.body, { headers: found.headers, status: found.status }) : undefined;
+      }
+      return store.get(request.url)?.clone();
+    },
+    async put(request: Request, response: Response) {
+      writes.push(request.url);
+      if (replayContext) {
+        replayContext.write(`stage/lifecycle/cache/${encodeURIComponent(request.url)}`, {
+          body: await response.clone().text(),
+          headers: Object.fromEntries(response.headers.entries()),
+          status: response.status,
+        });
+        return;
+      }
+      store.set(request.url, response.clone());
+    },
+  } as unknown as Cache;
+  return { cache, reads, writes };
+}
+
+/** Exercise a true cold miss and warm clone-only hit without touching source keys. */
+export async function buildV84CloneCacheEvidence(
+  materialization: V84DisabledInstallMaterializationResult,
+  replayContext?: V84CleanCloneReplayContext,
+) {
+  const memory = fakeCache(replayContext);
+  const disabledCacheKeyBefore = pageCacheKey(
+    V84_NATIVE_CLONE_TENANT,
+    "/v84-lifecycle",
+    "",
+    1,
+    materialization.candidatePlanBefore.planRevision,
+  );
+  const cloneCacheKey = pageCacheKey(
+    V84_NATIVE_CLONE_TENANT,
+    "/v84-lifecycle",
+    "",
+    1,
+    materialization.candidatePlanAfter.planRevision,
+  );
+  const sourceCacheKey = pageCacheKey(V84_NATIVE_SOURCE_TENANT, "/v84-lifecycle", "", 1);
+  const cold = await getCachedPage(memory.cache, cloneCacheKey);
+  await putCachedPage(memory.cache, cloneCacheKey, new Response(CACHE_BODY, {
+    status: 200,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  }));
+  const warm = await getCachedPage(memory.cache, cloneCacheKey);
+  const warmBody = warm ? await warm.text() : "";
+  if (
+    cold !== null ||
+    !warm ||
+    warmBody !== CACHE_BODY ||
+    warm.headers.get("x-tot-cache") !== "hit" ||
+    disabledCacheKeyBefore.url !== cloneCacheKey.url ||
+    INTEGRATION_MARKUP.test(warmBody)
+  ) {
+    throw new Error("The clone-local warm-cache proof failed.");
+  }
+  if (memory.reads.includes(sourceCacheKey.url) || memory.writes.includes(sourceCacheKey.url)) {
+    throw new Error("The warm-cache proof touched the source namespace.");
+  }
+
+  return {
+    warmCache: {
+      tenant: V84_NATIVE_CLONE_TENANT,
+      coldMiss: true,
+      warmHit: true,
+      cloneWriteCount: memory.writes.length,
+      sourceReadCount: memory.reads.filter((url) => url === sourceCacheKey.url).length,
+      sourceWriteCount: memory.writes.filter((url) => url === sourceCacheKey.url).length,
+      managedInstallStateChanged: materialization.managedInstallStateChanged,
+      effectivePlanChanged:
+        materialization.candidatePlanBefore.planRevision !== materialization.candidatePlanAfter.planRevision,
+      disabledDraftsChangedCacheKey: disabledCacheKeyBefore.url !== cloneCacheKey.url,
+      artifactContainsIntegrationMarkup: INTEGRATION_MARKUP.test(warmBody),
+    },
+    cloneCacheReads: memory.reads.length,
+    cloneCacheWrites: memory.writes.length,
+  };
+}