@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -1,8 +1,8 @@
 /**
- * App registry service — PrivateApps epic, D2 (Chunk A). Owns the
+ * App registry service. Owns the
  * `app_installs` / `app_audit_log` rows described in `schema.ts` and
  * orchestrates credential lifecycle through the {@link CredentialPort} seam
- * (Chunk B implements it; Chunk A only depends on the interface, mirroring
+ * (the credential store implements it; this service depends only on the interface, mirroring
  * how `D1VersionStore` implements `@tot/private-controlplane`'s `VersionStore`
  * contract without either side importing the other's internals).
  *
@@ -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
@@ -131,7 +177,7 @@ export interface IssuedCredential {
 
 /**
  * `IssuedCredential` plus the one-time plaintext secret. `issue`/`rotate` mint
- * the secret, hash it for storage (Chunk B: `sha256Hex`), and hand the
+ * the secret, hash it for storage (`sha256Hex`), and hand the
  * plaintext back exactly once here — there is no "show secret again" path by
  * design, so a caller that discards this return has lost it for good (see
  * `AppRegistryService.install`'s `InstallResult`, which is why this seam
@@ -140,10 +186,10 @@ export interface IssuedCredential {
 export type IssuedCredentialSecret = IssuedCredential & { secret: string };
 
 /**
- * Minimal seam for the credential lifecycle a later chunk (D2 Chunk B)
+ * Minimal seam for the credential lifecycle the credential store
  * implements against `app_credentials`. `AppRegistryService` orchestrates
  * through this interface only — it never touches credential storage directly,
- * so Chunk A can ship and be tested (with a fake) without Chunk B existing.
+ * so it can be tested with a fake.
  */
 export interface CredentialPort {
   /** Issue a fresh client-credential set for a newly installed app. */
@@ -155,7 +201,7 @@ export interface CredentialPort {
 }
 
 /**
- * The 3 platform-owned widget slots (D5 Chunk A). Mirrors the `widgets[].placement`
+ * The 3 platform-owned widget slots. Mirrors the `widgets[].placement`
  * enum in `docs/private-apps/contract/tot-app.schema.json` — widgets render in a
  * platform-managed sandboxed iframe at one of these fixed slots, never as
  * merchant-pasted script at an app-chosen location.
@@ -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/scopes.ts

@@ -1,6 +1,6 @@
 /**
- * Scope validation — the compliance-floor gate for Storefront Private Apps
- * (PrivateApps epic, D2). See `docs/private-apps/feature-brief.md` §"The
+ * Scope validation — the compliance-floor gate for Storefront Private Apps.
+ * See `docs/private-apps/feature-brief.md` §"The
  * compliance floor" and the machine-readable contract:
  *   - `docs/private-apps/contract/scopes.json` — the 8-scope V1 catalog.
  *   - `docs/private-apps/contract/forbidden-scopes.json` — the 8 ids that map

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/tokenIssuer.ts

@@ -1,7 +1,7 @@
 /**
  * OAuth2 client-credentials token issuer — the Storefront App Gateway's
- * `POST /oauth/token` grant (PrivateApps epic, D2 Chunk B). Mints the
- * short-lived RS256 JWT a private app presents as a bearer token to the D3
+ * `POST /oauth/token` grant. Mints the
+ * short-lived RS256 JWT a private app presents as a bearer token to the
  * scoped APIs.
  *
  * `tenant` and `env` are supplied by the CALLER (the route, from
@@ -97,8 +97,8 @@ export class AppTokenIssuer {
       tenant: install.tenantId,
       env: install.env,
       scopes: install.scopes,
-      // Discriminates this bearer token from a widget launch token (D5 Chunk
-      // B) so the two can never be replayed for each other even though both
+      // Discriminates this bearer token from a widget launch token so the two
+      // can never be replayed for each other even though both
       // are RS256 JWTs signed by the same gateway key — see tokenVerifier.ts.
       token_use: "access",
     })

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

@@ -1,7 +1,7 @@
 /**
  * Offline verification of the Storefront App Gateway's own OAuth2
- * client-credentials JWT (PrivateApps epic, D2 Chunk B) — this is what D3
- * imports at the scoped-API boundary to authorize an app's request.
+ * client-credentials JWT — this is what the scoped-API boundary
+ * imports to authorize an app's request.
  *
  * Modeled directly on `../auth/identityToken.ts`'s `IdentityAssertionVerifier`
  * (same `jwtVerify` + JWKS-by-`kid` shape, `aud`/`iss` pinning, alg allowlist),
@@ -25,7 +25,7 @@ import {
 } from "./gatewayKeys.js";
 import { readEnv } from "@/lib/env";
 
-/** The verified app-token claims (D3's authorization input). */
+/** The verified app-token claims (the scoped API's authorization input). */
 export interface AppTokenClaims {
   iss: string;
   sub: string; // install id
@@ -40,8 +40,8 @@ export interface AppTokenClaims {
 
 /** Normalize a jose JWT payload into typed {@link AppTokenClaims}, throwing on any missing claim. */
 function toAppTokenClaims(payload: Record<string, unknown>): AppTokenClaims {
-  // The security-critical discriminator: a widget launch token (D5 Chunk B,
-  // `token_use: "widget_launch"`) is signed by this SAME gateway key, so
+  // The security-critical discriminator: a widget launch token
+  // (`token_use: "widget_launch"`) is signed by this SAME gateway key, so
   // signature/aud/iss/exp checks alone can't tell it apart from a bearer
   // token. Requiring `token_use === "access"` here is what stops a launch
   // token — minted for a sandboxed iframe, short-TTL, no scopes checked —
@@ -128,7 +128,7 @@ export class AppTokenVerifier {
 /**
  * Get (or build) the verifier for one tenant, from the gateway's own
  * locally-derived JWKS. Returns `null` when the signing key isn't configured
- * — callers (D3 routes) fail closed with 503, mirroring `getIdentityVerifier`.
+ * — callers (the scoped-API routes) fail closed with 503, mirroring `getIdentityVerifier`.
  * Not cached across calls (unlike `identityToken.ts`'s remote-fetch verifier):
  * deriving the local JWKS is cheap (`gatewayKeys.ts` caches the export itself).
  */