@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/lib/admin/adminShell.ts

@@ -0,0 +1,292 @@
+/**
+ * Admin console shell client logic — hash-router tab switching, the floating
+ * Ask envelope, tenant-picker navigation, and roving-tabindex keyboard nav for
+ * the tablists. Imported from a processed `<script>` in admin.astro (ADR 0013):
+ * type-checked, bundled, tree-shaken, and its bundle hash is in the enforced
+ * CSP. The Ask envelope is built with the shared, unit-tested
+ * `buildAskEnvelope` (ai/askEnvelope) instead of a hand-copied inline mirror.
+ *
+ * There is no chat backend yet — the Ask envelope is emitted for dev inspection
+ * only (window.__toTAdminAsk + a "tot:admin-ask" CustomEvent), never sent over
+ * the network.
+ */
+import { buildAskEnvelope, type AskEnvelope } from "./ai/askEnvelope";
+
+const TAB_IDS = [
+  "orders",
+  "products",
+  "subscriptions",
+  "customers",
+  "fulfillment",
+  "reporting",
+  "ai-workflows",
+  "blog",
+  "publish",
+  "integrations",
+  "settings",
+] as const;
+
+const ASK_CONTEXTS: Record<string, string> = {
+  orders: "Orders",
+  products: "Products",
+  subscriptions: "Subscriptions",
+  customers: "Customers",
+  fulfillment: "Fulfillment",
+  reporting: "Reporting",
+  "ai-workflows": "AI Workflows",
+  blog: "Blog",
+  publish: "Publish",
+  integrations: "Integrations",
+  settings: "Settings",
+};
+
+declare global {
+  interface Window {
+    __toTAdminAsk?: AskEnvelope;
+  }
+}
+
+export function initAdminShell(): void {
+  const tabSet = new Set<string>(TAB_IDS);
+  const tabHashPattern = new RegExp(`^#(${TAB_IDS.join("|")})$`);
+  const canViewInternalGuide =
+    document.documentElement.dataset.internalAdminGuide === "true";
+  const defaultTab = canViewInternalGuide ? "orders" : "settings";
+
+  const buildAskEnvelopeForTab = (id: string): AskEnvelope => {
+    const root = document.documentElement.dataset;
+    const isStaff = root.adminIsStaff === "true";
+    const panel = document.getElementById(id);
+    const selectedRecordId =
+      panel?.querySelector<HTMLElement>("[data-admin-selected-id]")?.dataset
+        .adminSelectedId || null;
+
+    return buildAskEnvelope({
+      tenant: {
+        adminAppTenant: root.adminAppTenant ?? "",
+        targetTenant: root.adminTargetTenant ?? "",
+        operator: root.adminOperator || null,
+      },
+      isStaff,
+      activeTab: id,
+      selectedRecordId,
+    });
+  };
+
+  const setAskContext = (id: string): void => {
+    const label = ASK_CONTEXTS[id] ?? "Storefront";
+    const askButton = document.querySelector<HTMLElement>("[data-admin-ask]");
+    const askContext = document.querySelector<HTMLElement>(
+      "[data-admin-ask-context]",
+    );
+
+    if (askContext) askContext.textContent = label;
+    if (askButton) {
+      askButton.setAttribute("aria-label", `Ask about ${label}`);
+      askButton.setAttribute("title", `Ask about ${label}`);
+      askButton.dataset.askScope = id;
+    }
+
+    window.__toTAdminAsk = buildAskEnvelopeForTab(id);
+  };
+
+  const panelIdFromHash = (): string | null => {
+    const rawHash = window.location.hash.slice(1);
+    // The tab id is the part before any "?" query suffix (#publish?pr=42);
+    // the raw hash is still used for internal-guide anchor resolution.
+    const hash = rawHash.split("?")[0] ?? "";
+    if (!rawHash) return defaultTab;
+    if (tabSet.has(hash)) return hash;
+    if (!canViewInternalGuide) return defaultTab;
+
+    const target = rawHash ? document.getElementById(rawHash) : null;
+    const panel = target?.closest<HTMLElement>("[data-admin-panel]");
+    if (panel?.id && tabSet.has(panel.id)) return panel.id;
+
+    return null;
+  };
+
+  const setActiveTab = (id: string): void => {
+    if (!tabSet.has(id)) return;
+
+    document.documentElement.dataset.adminMode = "work-area";
+    document.documentElement.dataset.adminTab = id;
+    setAskContext(id);
+
+    document.querySelectorAll<HTMLElement>("[data-admin-panel]").forEach((panel) => {
+      const active = panel.id === id;
+      panel.hidden = !active;
+      panel.setAttribute("aria-hidden", active ? "false" : "true");
+    });
+
+    document
+      .querySelectorAll<HTMLAnchorElement>("[data-admin-tab-link]")
+      .forEach((link) => {
+        const active = link.hash === `#${id}`;
+        link.classList.toggle("active", active);
+
+        if (link.getAttribute("role") === "tab") {
+          link.setAttribute("aria-selected", active ? "true" : "false");
+          link.tabIndex = active ? 0 : -1;
+        }
+      });
+  };
+
+  const setGuideMode = (): void => {
+    if (!canViewInternalGuide) {
+      setActiveTab(defaultTab);
+      return;
+    }
+
+    document.documentElement.dataset.adminMode = "guide";
+    setAskContext(defaultTab);
+
+    document.querySelectorAll<HTMLElement>("[data-admin-panel]").forEach((panel) => {
+      panel.hidden = true;
+      panel.setAttribute("aria-hidden", "true");
+    });
+
+    document
+      .querySelectorAll<HTMLAnchorElement>("[data-admin-tab-link]")
+      .forEach((link) => {
+        link.classList.remove("active");
+
+        if (link.getAttribute("role") === "tab") {
+          link.setAttribute("aria-selected", "false");
+          link.tabIndex = 0;
+        }
+      });
+  };
+
+  const scrollWorkspaceToTop = (): void => {
+    const scroller = document.querySelector<HTMLElement>(".main");
+    const reset = (): void => {
+      if (scroller) {
+        scroller.scrollTo({ top: 0, left: 0 });
+        return;
+      }
+
+      window.scrollTo({ top: 0, left: 0 });
+    };
+
+    reset();
+    requestAnimationFrame(reset);
+    setTimeout(reset, 0);
+  };
+
+  const scrollToHashTarget = (panelId: string): void => {
+    const hash = window.location.hash.slice(1);
+    const target = hash ? document.getElementById(hash) : null;
+
+    if (!target || tabSet.has(hash) || target.id === panelId) {
+      scrollWorkspaceToTop();
+      return;
+    }
+
+    target?.scrollIntoView({ block: "start" });
+  };
+
+  const activateFromHash = ({ scroll = false }: { scroll?: boolean } = {}): void => {
+    const panelId = panelIdFromHash();
+
+    if (panelId) {
+      setActiveTab(panelId);
+      // Strip any query suffix before deciding whether the hash names a
+      // real tab — a valid deep link like #publish?pr=42 must not be
+      // normalized away to #settings for merchant viewers.
+      const hashTab = window.location.hash.slice(1).split("?")[0] ?? "";
+      if (!canViewInternalGuide && !tabSet.has(hashTab)) {
+        history.replaceState(null, "", "#settings");
+      }
+      if (scroll) requestAnimationFrame(() => scrollToHashTarget(panelId));
+      return;
+    }
+
+    setGuideMode();
+    if (scroll) {
+      const hash = window.location.hash.slice(1);
+      requestAnimationFrame(() =>
+        document.getElementById(hash)?.scrollIntoView({ block: "start" }),
+      );
+    }
+  };
+
+  document
+    .querySelector<HTMLSelectElement>("[data-admin-tenant-picker-select]")
+    ?.addEventListener("change", (event) => {
+      const params = new URLSearchParams(window.location.search);
+      params.set("asTenant", (event.target as HTMLSelectElement).value);
+      window.location.assign(
+        `${window.location.pathname}?${params}${window.location.hash}`,
+      );
+    });
+
+  // Emit the Ask envelope on open. No chat backend yet — dev-inspectable
+  // only via window.__toTAdminAsk (already kept current by setAskContext)
+  // and this "tot:admin-ask" CustomEvent.
+  document.querySelector("[data-admin-ask]")?.addEventListener("click", () => {
+    const activeTab = document.documentElement.dataset.adminTab ?? defaultTab;
+    const envelope = buildAskEnvelopeForTab(activeTab);
+    window.__toTAdminAsk = envelope;
+    document.dispatchEvent(new CustomEvent("tot:admin-ask", { detail: envelope }));
+    if (
+      window.location.hostname === "localhost" ||
+      window.location.hostname === "127.0.0.1"
+    ) {
+      console.debug("[admin:ask]", envelope);
+    }
+  });
+
+  document.addEventListener("click", (event) => {
+    const target =
+      event.target instanceof Element
+        ? event.target
+        : (event.target as Node | null)?.parentElement ?? null;
+    const link = target?.closest<HTMLAnchorElement>("a[href^='#']");
+    if (!link || !tabHashPattern.test(link.hash)) return;
+
+    event.preventDefault();
+    const id = link.hash.slice(1);
+    setActiveTab(id);
+    history.pushState(null, "", link.hash);
+    scrollWorkspaceToTop();
+  });
+
+  document.addEventListener("keydown", (event) => {
+    const target = event.target instanceof Element ? event.target : null;
+    const currentTab = target?.closest<HTMLElement>(
+      "[role='tab'][data-admin-tab-link]",
+    );
+    if (!currentTab) return;
+
+    // Filter to visible tabs only: the mobile tab bar and the internal
+    // Admin Tab Map can both be present in the DOM at once (one hidden
+    // via CSS depending on viewport/viewer), and this selector matches
+    // role="tab" elements in either — without this filter, arrow/home/
+    // end navigation could walk into a display:none tablist whose
+    // .focus() is a silent no-op.
+    const tabs = Array.from(
+      document.querySelectorAll<HTMLElement>("[role='tab'][data-admin-tab-link]"),
+    ).filter((el) => el.offsetParent !== null);
+    const currentIndex = tabs.indexOf(currentTab);
+    let nextIndex = currentIndex;
+
+    if (event.key === "ArrowRight") nextIndex = (currentIndex + 1) % tabs.length;
+    if (event.key === "ArrowLeft")
+      nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+    if (event.key === "Home") nextIndex = 0;
+    if (event.key === "End") nextIndex = tabs.length - 1;
+
+    if (nextIndex === currentIndex) return;
+
+    const nextTab = tabs[nextIndex];
+    if (!nextTab) return;
+
+    event.preventDefault();
+    nextTab.focus();
+    nextTab.click();
+  });
+
+  window.addEventListener("hashchange", () => activateFromHash({ scroll: true }));
+  activateFromHash({ scroll: Boolean(window.location.hash) });
+}

package/apps/storefront/src/lib/admin/ai/approvalMode.ts

@@ -1,7 +1,6 @@
 /**
- * Canonical approval state machine (baseline §Settings / §AI Workflows,
- * ai-evidence-substrate item d). `settings.ts` and `aiWorkflows.ts` previously
- * declared their own copies of this union; both now import it from here.
+ * Canonical approval state machine. `settings.ts` and `aiWorkflows.ts` import
+ * this union from here.
  */
 export type ApprovalMode = "draft_only" | "approval_required" | "guarded_automation";
 

package/apps/storefront/src/lib/admin/ai/audit.ts

@@ -1,9 +1,7 @@
 /**
- * Canonical audit event model (baseline "Audit logs must record both the
- * operator and the target tenant"; ai-evidence-substrate item e). Every
- * mutation-shaped or AI-suggested action in the admin console should record
- * one of these, keyed by `targetTenant` — never `adminAppTenant`, per
- * decision `tenant-envelope-contract`.
+ * Canonical audit event model — records both the operator and the target
+ * tenant. Every mutation-shaped or AI-suggested action in the admin console
+ * should record one of these, keyed by `targetTenant` — never `adminAppTenant`.
  */
 export interface AuditEvent {
   /** The signed-in operator's email, or a system actor id for automation-triggered events. */

package/apps/storefront/src/lib/admin/checkoutStyleInput.ts

@@ -1,23 +1,23 @@
 /**
  * Validate + sanitize merchant-submitted checkout styling into a safe, complete
- * `CheckoutStyle` before it is published to the versioned spine (U12 save path).
+ * `CheckoutStyle` before it is published to the versioned spine (the save path).
  *
  * The submitted body is a partial (`DeepPartial<CheckoutStyle>`): a merchant may
  * set one field without restating the rest, so this merges any valid override
- * over `DEFAULT_CHECKOUT_STYLE` (reusing U10's `mergeCheckoutStyle`) and returns a
- * complete descriptor. It is the WRITE-side guard; the go-live GateReport (U13)
+ * over `DEFAULT_CHECKOUT_STYLE` (reusing `mergeCheckoutStyle`) and returns a
+ * complete descriptor. It is the WRITE-side guard; the GateReport
  * still does the deeper compliance/contrast/perf pass on promote.
  *
  * Two hard constraints enforced here:
  *   - **ASCII-safe.** Hosted checkout cache pass is not Unicode-safe — a non-ASCII
- *     byte in a value that U11 renders into the pushed CSS can blank the checkout.
+ *     byte in a value rendered into the pushed CSS can blank the checkout.
  *     Every provided string leaf must be printable ASCII.
- *   - **CSS-token hygiene.** These values are interpolated into generated CSS
- *     (U11), so we reject the characters that could break out of a declaration
+ *   - **CSS-token hygiene.** These values are interpolated into generated CSS,
+ *     so we reject the characters that could break out of a declaration
  *     (`;` `{` `}` `<` `>` and newlines). Defense-in-depth, not the full gate.
  *
  * Pure + dependency-free (no I/O, no Astro): unit-testable in isolation and safe
- * to reuse from the gate (U13) or the CSS renderer (U11) if promoted to
+ * to reuse from the gate or the CSS renderer if promoted to
  * public-runtime later.
  */
 import {

package/apps/storefront/src/lib/admin/checkoutStyleTarget.ts

@@ -1,9 +1,9 @@
 /**
- * Decide which tenant a checkout-style save may write to (U12b — staff
- * cross-tenant save).
+ * Decide which tenant a checkout-style save may write to — staff cross-tenant
+ * save.
  *
  * The base save gate (`resolveOwnerSession`) resolves the operator's OWN tenant
- * (the routed appDomain). U12 always wrote there. But a ToT-staff operator can
+ * (the routed appDomain). But a ToT-staff operator can
  * "operate as" another tenant via the admin picker (`?asTenant=`), and their
  * save must land on THAT tenant's artifact — provided they're actually
  * authorized for it. This resolver makes that decision, and it deliberately

package/apps/storefront/src/lib/admin/envelope.ts

@@ -4,7 +4,6 @@
  * staff-override authorization (`resolveAdminTenantMode`) that admin.astro
  * actually runs. This module re-exports that type so every mock service under
  * `lib/admin/**` can keep importing it from a stable relative path
- * (`../../envelope`) without declaring a second, competing interface (decision
- * `envelope-type-duplication-follow-up`).
+ * (`../../envelope`) without declaring a second, competing interface.
  */
 export type { AdminTenantEnvelope } from "@/lib/adminTenantEnvelope";

package/apps/storefront/src/lib/admin/orderClient.ts

@@ -1,5 +1,5 @@
 /**
- * Server-side client for the checkout order READ API (card 8585 / U2).
+ * Server-side client for the checkout order READ API.
  *
  * Calls `GET /commerce/orders[/:orderId]` with the tenant's per-tenant bearer key
  * (the ToT `partnerApi.apiKey`, held as a Worker secret — NEVER shipped to the
@@ -8,8 +8,7 @@
  *
  * The fetch runs on the Cloudflare Worker (server), so the call is same-origin →
  * cross-service server-to-server; it is NOT browser-originated and therefore not
- * CSP-governed — the U2 CSP connect-src entry is intentionally skipped (board
- * decision `u2-csp-server-side-fetch`).
+ * CSP-governed — the CSP connect-src entry is intentionally skipped.
  *
  * `fetchImpl` is injectable so the client is unit-testable offline.
  */
@@ -68,8 +67,7 @@ export interface CheckoutOrderClientConfig {
 /**
  * Resolve the checkout order API base URL for an environment (contract §2).
  * qa/test use the non-prod proxy; live uses prod. Kept private so it does not
- * collide with U11b's exported checkout theme base URL before the units fold;
- * the integrator can dedup into one shared export.
+ * collide with the exported checkout theme base URL.
  */
 export function orderApiBaseUrl(env: CustomizationEnv): string {
   return env === "live"

package/apps/storefront/src/lib/admin/services/orders.ts

@@ -1,22 +1,20 @@
 /**
- * REAL orders view model (card 8585 / U3) — replaces the deterministic mock as
- * the Orders tab's data source. Fetches the tenant's checkout orders via U2's
- * order client and maps the frozen DTO (`@tot/public-runtime` checkout-orders)
- * into the EXISTING `OrdersViewModel` shape, so `OrdersWorkspace.astro` renders
- * unchanged. Read-only (scope-locks) — no write paths.
+ * REAL orders view model — the Orders tab's data source. Fetches the tenant's
+ * checkout orders via the order client and maps the frozen DTO
+ * (`@tot/public-runtime` checkout-orders) into the `OrdersViewModel` shape that
+ * `OrdersWorkspace.astro` renders. Read-only (scope-locks) — no write paths.
  *
  * The mapping is a pure function (`mapOrdersToViewModel`) for testability; the
  * orchestration (`getOrdersViewModel`) lists orders, eagerly fetches each order's
  * detail (OrdersWorkspace renders `detailsById[row.id]` for every row), and maps.
- * On ANY upstream failure it returns a valid EMPTY view model so the tab renders
- * (rich loading/empty/error UX is U5). NOTE: the live "real qa data" path is
- * gated on ToT-core exposing `GET /api/exciseTax/orders` (see U1/U2 notes); until
- * then this yields the empty model on qa.
+ * On ANY upstream failure it returns a valid EMPTY view model so the tab renders.
+ * The live "real qa data" path is gated on ToT-core exposing
+ * `GET /api/exciseTax/orders`; until that exists this yields the empty model on qa.
  *
  * Identity/age fields (riskLevel, readiness "identity_and_age", evidence) are
- * derived provisionally from commerce facts here; U4 (the tot20 verification
- * join) fills them authoritatively via the DTO's null `verification` /
- * `verificationDetail` slots — no shape change needed.
+ * derived provisionally from commerce facts here; the tot20 verification join
+ * fills them authoritatively via the DTO's null `verification` /
+ * `verificationDetail` slots.
  */
 import type {
   CheckoutOrderDetail,
@@ -45,7 +43,7 @@ function deriveNextStep(fulfillment: OrderShipState, blocker: string | null): st
   return "Create label";
 }
 
-/** Provisional risk until U4 fills `verification`. Prefer a real riskLevel when present. */
+/** Provisional risk until the verification join fills `verification`. Prefer a real riskLevel when present. */
 function deriveRisk(
   verification: CheckoutOrderVerification | null,
   blocker: string | null,
@@ -75,7 +73,7 @@ export function mapSummaryToRow(s: CheckoutOrderSummary): OrderRow {
   };
 }
 
-/** Commerce-derived readiness checks (U4 enriches the identity dimension). */
+/** Commerce-derived readiness checks (the verification join enriches the identity dimension). */
 function deriveReadinessChecks(d: CheckoutOrderDetail): OrderReadinessCheck[] {
   const ageHold = d.blocker === "Age verification hold";
   return [
@@ -118,7 +116,7 @@ function deriveReadinessChecks(d: CheckoutOrderDetail): OrderReadinessCheck[] {
   ];
 }
 
-/** Base commerce evidence events (U4 replaces with the real verification timeline). */
+/** Base commerce evidence events (the verification join replaces with the real verification timeline). */
 function deriveEvidenceTimeline(d: CheckoutOrderDetail): OrderEvidenceEvent[] {
   const events: OrderEvidenceEvent[] = [
     { title: "Order imported", detail: "Storefront order became available in the admin queue.", at: d.placedAt },
@@ -226,7 +224,7 @@ export interface GetOrdersViewModelOptions {
  * the Orders tab always renders.
  */
 /**
- * Load outcome for the Orders tab (U5) — lets the UI pick the right state:
+ * Load outcome for the Orders tab — lets the UI pick the right state:
  * `loaded` (rows), `empty` (fetch OK, 0 orders), `error` (upstream failed), and
  * `not_configured` (produced by the caller when no bearer/client is available —
  * the service itself never returns it). `page` carries the pagination cursor.
@@ -240,7 +238,7 @@ export interface OrdersLoadResult {
 }
 
 /**
- * Parse server-backed list filters from a request's query string (U5). `queue`
+ * Parse server-backed list filters from a request's query string. `queue`
  * of `"all"` (or absent) means no server filter. Non-numeric `limit` is ignored.
  * `payment`/search are NOT here — they are client-side refinements (the DTO list
  * API has no payment filter, per contract §9).
@@ -263,7 +261,7 @@ export function parseOrderFilters(params: URLSearchParams): CheckoutOrderListFil
 }
 
 /**
- * Fetch + map the orders view model AND report the load outcome (U5). Lists,
+ * Fetch + map the orders view model AND report the load outcome. Lists,
  * eagerly fetches per-order detail, maps. Distinguishes empty from error so the
  * tab can degrade gracefully. Never throws.
  */
@@ -292,7 +290,7 @@ export async function getOrdersViewModelResult(
   }
 }
 
-/** Back-compat convenience: just the view model (see getOrdersViewModelResult). */
+/** Convenience wrapper: just the view model (see getOrdersViewModelResult). */
 export async function getOrdersViewModel(
   opts: GetOrdersViewModelOptions,
 ): Promise<OrdersViewModel> {

package/apps/storefront/src/lib/admin/viewmodels/aiWorkflows.ts

@@ -1,10 +1,8 @@
 /**
- * AI Workflows view model (baseline §AI Workflows) — the 8 named recurring
- * jobs as a control-plane record. No execution: this unit only defines the
- * read-oriented record shape (ai-workflows-scaffold/operational build the tab
- * + execution on top of it). `ApprovalMode`/`AuditEvent`/`AiRecommendation`
- * now come from the ai-evidence-substrate (`lib/admin/ai`), which formalizes
- * the approval/evidence models this view model originally stubbed.
+ * AI Workflows view model — the 8 named recurring jobs as a control-plane
+ * record. No execution: this defines only the read-oriented record shape; the
+ * tab + execution build on top of it. `ApprovalMode`/`AuditEvent`/`AiRecommendation`
+ * come from `lib/admin/ai`, which formalizes the approval/evidence models.
  */
 
 import type { ApprovalMode } from "../ai/approvalMode";

package/apps/storefront/src/lib/admin/viewmodels/settings.ts

@@ -54,7 +54,7 @@ export interface SettingsViewModel {
   auditTrail: SettingsAuditEvent[];
   /**
    * The target tenant's current checkout styling — the editable descriptor the
-   * "Checkout styling" section (U12) renders in its editor and saves back through
+   * "Checkout styling" section renders in its editor and saves back through
    * the versioned publish spine (`POST /api/admin/checkout-style` →
    * `publishToTest` on `tenants/<id>/checkout-style.json`). Always a complete
    * `CheckoutStyle` (the resolved default merged with any published override), so

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

@@ -1,8 +1,8 @@
 /**
- * Composition root + shared helpers for the `/api/apps/admin/*` routes
- * (PrivateApps epic, D2 Chunk C) — builds an `AppRegistryService` over the
+ * Composition root + shared helpers for the `/api/apps/admin/*` routes —
+ * builds an `AppRegistryService` over the
  * `STOREFRONT_APPS_DB` `Queryable` binding and a `D1CredentialStore`, the same
- * construction `api/apps/oauth/token.ts` (Chunk B) uses, and mirrors
+ * construction `api/apps/oauth/token.ts` uses, and mirrors
  * `../grants/route.ts`'s `getService()` + no-store `json()` + 503-when-
  * unconfigured pattern. Kept out of the pure service module so that stays
  * transport-free and unit-testable against a fake `Queryable`.
@@ -18,6 +18,7 @@ import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "./gatewayKeys.js";
 import { fromD1 } from "../d1/catalog.js";
 import { readD1, readEnv } from "../env.js";
 import { MANAGE_ROLES, type AdminAuthResult } from "./adminSession.js";
+import { ManagedAnalyticsApiV1Facade } from "./managedAnalyticsService.js";
 
 /**
  * No-store JSON response — install/rotate bodies carry a one-time client
@@ -44,6 +45,13 @@ export async function getRegistryService(): Promise<AppRegistryService | Respons
   return new AppRegistryService(db, credentials);
 }
 
+/** Build the managed-analytics v1 service over the same tenant control-plane D1. */
+export async function getManagedAnalyticsService(): Promise<ManagedAnalyticsApiV1Facade | Response> {
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "app registry not configured" }, 503);
+  return new ManagedAnalyticsApiV1Facade(fromD1(d1));
+}
+
 /** HTTP status per `RegistryError` code — the one shared fail-closed mapping. */
 const STATUS_BY_REGISTRY_CODE: Record<RegistryErrorCode, number> = {
   scope_denied: 400,
@@ -52,6 +60,8 @@ const STATUS_BY_REGISTRY_CODE: Record<RegistryErrorCode, number> = {
   invalid_state: 409,
   invalid_webhook_endpoint: 400,
   invalid_widget_placement: 400,
+  unknown_version: 404,
+  invalid_version_facets: 400,
 };
 
 /** Map a `RegistryError` to its HTTP status. Never echoes internals — code + message only. */
@@ -72,7 +82,7 @@ export function parseInstallId(body: unknown): string | null {
  * Resolve `installId` and verify it belongs to `tenantId` — every mutating
  * admin route (update/suspend/resume/uninstall/rotate) MUST call this BEFORE
  * invoking a service method, since those methods take a bare `installId` with
- * no tenant check of their own (Chunk A assumption #1). A foreign-tenant
+ * no tenant check of their own. A foreign-tenant
  * `installId` is reported IDENTICALLY to a truly-missing one — 404, same
  * body shape as `RegistryError("not_found")` — so there is no cross-tenant
  * existence oracle.