@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export type ApprovalMode = "draft_only" | "approval_required" | "guarded_automation";
+
+/** A `draft_only` recommendation must never be auto-applied; a human authors the action from it. */
+export function isDraftOnly(mode: ApprovalMode): boolean {
+  return mode === "draft_only";
+}
+
+/** An `approval_required` recommendation can be pre-drafted but needs an explicit human approval before it takes effect. */
+export function requiresHumanApproval(mode: ApprovalMode): boolean {
+  return mode === "approval_required";
+}
+
+/** Only `guarded_automation` may execute without a human in the loop for that specific action. */
+export function isAutomationAllowed(mode: ApprovalMode): boolean {
+  return mode === "guarded_automation";
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The floating `Ask` button's context envelope (baseline §Horizontal AI
+ * Concepts / Ask; ai-evidence-substrate item a). PURE + no I/O so it is
+ * unit-testable and reusable from both the inline admin.astro script (via a
+ * plain-object mirror, since `is:inline` scripts cannot import modules) and
+ * any future server-side Ask route. There is no chat backend yet — today
+ * this is emitted for dev inspection only (see admin.astro's `data-admin-ask`
+ * click handler), never sent over the network.
+ */
+import type { AdminTenantEnvelope } from "../envelope";
+
+export type AdminRole = "internal_staff" | "merchant_operator";
+
+export interface AskEnvelope {
+  tenant: AdminTenantEnvelope;
+  /** The active tab's `data-agent-scope` value, e.g. "orders". */
+  activeTab: string;
+  /** The currently selected row/detail record id, if the active tab has one selected. */
+  selectedRecordId: string | null;
+  role: AdminRole;
+  permissions: string[];
+  /** Active filters / saved view, if the active tab has any applied. */
+  filters: Record<string, string>;
+  /** Evidence reference ids (evidenceReference.ts) relevant to the current view/selection. */
+  evidenceContext: string[];
+}
+
+const STAFF_PERMISSIONS = ["internal_admin", "cross_tenant_read"] as const;
+const MERCHANT_PERMISSIONS = ["merchant_admin"] as const;
+
+export function buildAskEnvelope(input: {
+  tenant: AdminTenantEnvelope;
+  isStaff: boolean;
+  activeTab: string;
+  selectedRecordId?: string | null;
+  filters?: Record<string, string>;
+  evidenceContext?: string[];
+}): AskEnvelope {
+  return {
+    tenant: input.tenant,
+    activeTab: input.activeTab,
+    selectedRecordId: input.selectedRecordId ?? null,
+    role: input.isStaff ? "internal_staff" : "merchant_operator",
+    permissions: input.isStaff ? [...STAFF_PERMISSIONS] : [...MERCHANT_PERMISSIONS],
+    filters: input.filters ?? {},
+    evidenceContext: input.evidenceContext ?? [],
+  };
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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`.
+ */
+export interface AuditEvent {
+  /** The signed-in operator's email, or a system actor id for automation-triggered events. */
+  operator: string;
+  targetTenant: string;
+  action: string;
+  at: string;
+}

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

@@ -0,0 +1,6 @@
+export type { ApprovalMode } from "./approvalMode";
+export { isDraftOnly, requiresHumanApproval, isAutomationAllowed } from "./approvalMode";
+export type { AuditEvent } from "./audit";
+export type { AiRecommendation } from "./recommendation";
+export type { AskEnvelope, AdminRole } from "./askEnvelope";
+export { buildAskEnvelope } from "./askEnvelope";

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

@@ -0,0 +1,155 @@
+/**
+ * Makes 3 of the 8 scaffolded AI Workflows (ai-workflows-scaffold) run
+ * end-to-end against the mock source domains (baseline §AI Workflows +
+ * §Suggested Buildout Sequence step 11). Still NO external side effects —
+ * "execution" here means producing an evidence-backed, approval-gated
+ * AiRecommendation plus a deterministic run history, never a real mutation.
+ * The other 5 workflows remain scaffold-only until their own units connect
+ * real source data.
+ */
+import type { AdminTenantEnvelope } from "../envelope";
+import { getOrdersViewModel, getProductsViewModel, getEvidenceViewModel } from "../services/mock";
+import { MOCK_ANCHOR_ISO, offsetIso, randomInt, seededRandom } from "../seed";
+import { OPERATIONAL_WORKFLOW_KEYS, type OperationalWorkflowKey } from "../viewmodels/aiWorkflows";
+import type { ApprovalMode } from "./approvalMode";
+import type { AuditEvent } from "./audit";
+import type { AiRecommendation } from "./recommendation";
+
+export { OPERATIONAL_WORKFLOW_KEYS, type OperationalWorkflowKey };
+
+export interface WorkflowRunResult {
+  recommendation: AiRecommendation;
+  runHistory: AuditEvent[];
+}
+
+function buildRunHistory(input: {
+  targetTenant: string;
+  runKey: string;
+  count: number;
+  action: string;
+}): AuditEvent[] {
+  const rng = seededRandom(`workflow-run:${input.runKey}:${input.targetTenant}`);
+  const history: AuditEvent[] = [];
+  let at = MOCK_ANCHOR_ISO;
+  for (let i = 0; i < input.count; i += 1) {
+    at = offsetIso(at, -randomInt(rng, 300, 2400));
+    history.push({ operator: "system:scheduler", targetTenant: input.targetTenant, action: input.action, at });
+  }
+  return history;
+}
+
+function runStockoutForecaster(envelope: AdminTenantEnvelope, approvalMode: ApprovalMode): WorkflowRunResult {
+  const products = getProductsViewModel(envelope);
+  const LOW_STOCK_THRESHOLD = 20;
+  const lowStock = products.rows
+    .flatMap((row) => {
+      const detail = products.detailsById[row.id]!;
+      return detail.variants
+        .filter((v) => v.inventory < LOW_STOCK_THRESHOLD)
+        .map((v) => ({ product: row, variant: v }));
+    })
+    .sort((a, b) => a.variant.inventory - b.variant.inventory);
+
+  const evidenceRefs = lowStock.map(({ product }) => `evidence:${envelope.targetTenant}:product:${product.id}`);
+  const summary =
+    lowStock.length === 0
+      ? "No variants below the reorder threshold — nothing to forecast this run."
+      : `${lowStock.length} variant(s) below ${LOW_STOCK_THRESHOLD} units, lowest: ${lowStock[0]!.variant.name} (${lowStock[0]!.product.name}) at ${lowStock[0]!.variant.inventory}.`;
+
+  return {
+    recommendation: {
+      summary,
+      confidence: lowStock.length > 0 ? 0.8 : 0.99,
+      evidenceRefs: [...new Set(evidenceRefs)],
+      owner: "Ops",
+      approvalMode,
+      auditTrail: [],
+    },
+    runHistory: buildRunHistory({
+      targetTenant: envelope.targetTenant,
+      runKey: "stockout-forecaster",
+      count: 3,
+      action: "Scanned product variant inventory for reorder thresholds",
+    }),
+  };
+}
+
+function runChargebackDefenseWatcher(envelope: AdminTenantEnvelope, approvalMode: ApprovalMode): WorkflowRunResult {
+  const orders = getOrdersViewModel(envelope);
+  const evidenceGraph = getEvidenceViewModel(envelope);
+  const holds = orders.rows.filter((r) => r.shipState === "hold_review_required");
+
+  const evidenceRefs = holds.flatMap((row) => {
+    const orderRefId = `evidence:${envelope.targetTenant}:order:${row.id}`;
+    const orderRef = evidenceGraph.find((e) => e.id === orderRefId);
+    return orderRef ? [orderRef.id, ...orderRef.relatedRefs] : [orderRefId];
+  });
+
+  const summary =
+    holds.length === 0
+      ? "No orders on hold — no dispute-evidence packets needed this run."
+      : `${holds.length} order(s) on hold need evidence assembled before the dispute window: ${holds.map((r) => r.id).join(", ")}.`;
+
+  return {
+    recommendation: {
+      summary,
+      confidence: holds.length > 0 ? 0.65 : 0.99,
+      evidenceRefs: [...new Set(evidenceRefs)],
+      owner: "Risk",
+      approvalMode,
+      auditTrail: [],
+    },
+    runHistory: buildRunHistory({
+      targetTenant: envelope.targetTenant,
+      runKey: "chargeback-defense-watcher",
+      count: 4,
+      action: "Checked held orders for missing dispute evidence",
+    }),
+  };
+}
+
+function runAiChannelReadinessAudit(envelope: AdminTenantEnvelope, approvalMode: ApprovalMode): WorkflowRunResult {
+  const products = getProductsViewModel(envelope);
+  const notReady = products.rows.filter((r) => !r.aiChannelReady);
+  const evidenceRefs = notReady.map((row) => `evidence:${envelope.targetTenant}:product:${row.id}`);
+
+  const summary =
+    notReady.length === 0
+      ? "Every product is AI channel ready — nothing to audit this run."
+      : `${notReady.length} of ${products.rows.length} products are not AI channel ready, blocked by ${notReady.reduce((sum, r) => sum + r.missingExciseCount, 0)} total excise metadata gaps.`;
+
+  return {
+    recommendation: {
+      summary,
+      confidence: notReady.length > 0 ? 0.75 : 0.99,
+      evidenceRefs: [...new Set(evidenceRefs)],
+      owner: "Products",
+      approvalMode,
+      auditTrail: [],
+    },
+    runHistory: buildRunHistory({
+      targetTenant: envelope.targetTenant,
+      runKey: "ai-channel-readiness-audit",
+      count: 2,
+      action: "Audited catalog for AI channel readiness gaps",
+    }),
+  };
+}
+
+const RUNNERS: Record<OperationalWorkflowKey, (envelope: AdminTenantEnvelope, approvalMode: ApprovalMode) => WorkflowRunResult> = {
+  "stockout-forecaster": runStockoutForecaster,
+  "chargeback-defense-watcher": runChargebackDefenseWatcher,
+  "ai-channel-readiness-audit": runAiChannelReadinessAudit,
+};
+
+export function isOperational(key: string): key is OperationalWorkflowKey {
+  return (OPERATIONAL_WORKFLOW_KEYS as readonly string[]).includes(key);
+}
+
+export function runOperationalWorkflow(
+  key: OperationalWorkflowKey,
+  envelope: AdminTenantEnvelope,
+  approvalMode: ApprovalMode,
+): WorkflowRunResult {
+  return RUNNERS[key](envelope, approvalMode);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The shared shape every AI-suggested action in the admin console carries
+ * (baseline: "Evidence, confidence, owner, approval mode, and audit history
+ * attached to recommendations"). `WorkflowRecord.suggestedAction` uses this;
+ * later units (Order Assist, Fulfillment Assist, etc.) should reuse it rather
+ * than inventing a parallel "suggestion" shape per tab.
+ */
+import type { ApprovalMode } from "./approvalMode";
+import type { AuditEvent } from "./audit";
+
+export interface AiRecommendation {
+  summary: string;
+  /** 0–1 confidence the recommendation is correct/safe to act on. */
+  confidence: number;
+  /** Ids into the evidence reference model (evidenceReference.ts) backing this recommendation. */
+  evidenceRefs: string[];
+  owner: string;
+  approvalMode: ApprovalMode;
+  auditTrail: AuditEvent[];
+}

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

@@ -0,0 +1,172 @@
+/**
+ * Validate + sanitize merchant-submitted checkout styling into a safe, complete
+ * `CheckoutStyle` before it is published to the versioned spine (U12 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)
+ * still does the deeper compliance/contrast/perf pass on promote.
+ *
+ * Two hard constraints enforced here (both from the epic's Foxy-theme reality):
+ *   - **ASCII-safe.** Foxy's 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.
+ *     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
+ *     (`;` `{` `}` `<` `>` 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
+ * public-runtime later.
+ */
+import {
+  DEFAULT_CHECKOUT_STYLE,
+  mergeCheckoutStyle,
+  type CheckoutStyle,
+  type CheckoutStyleColors,
+} from "@tot/public-runtime";
+
+export type CheckoutStyleInputResult =
+  | { ok: true; style: CheckoutStyle }
+  | { ok: false; errors: string[] };
+
+/** Per-field length ceilings — generous enough for real stacks, tight enough to
+ *  bound what gets pushed to Foxy. */
+const MAX = {
+  color: 64,
+  fontFamily: 200,
+  length: 16,
+  logoUrl: 500,
+} as const;
+
+const COLOR_KEYS: (keyof CheckoutStyleColors)[] = [
+  "background",
+  "surface",
+  "primary",
+  "primaryContrast",
+  "accent",
+  "text",
+];
+
+/** Printable ASCII only (0x20–0x7E). Rejects control chars, newlines, and any
+ *  non-ASCII (the Foxy-cache Unicode hazard). */
+function isPrintableAscii(value: string): boolean {
+  return /^[\x20-\x7E]*$/.test(value);
+}
+
+/** CSS-value hygiene: no declaration/selector-breaking characters. */
+function hasUnsafeCssChars(value: string): boolean {
+  return /[;{}<>]/.test(value);
+}
+
+/**
+ * Validate one string leaf: must be a string, printable ASCII, within `max`, free
+ * of CSS-breaking characters, and (unless `allowEmpty`) non-empty after trim.
+ * Returns the trimmed value or pushes a labeled error.
+ */
+function takeString(
+  raw: unknown,
+  label: string,
+  max: number,
+  errors: string[],
+  allowEmpty = false,
+): string | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== "string") {
+    errors.push(`${label} must be a string`);
+    return undefined;
+  }
+  const value = raw.trim();
+  if (!value) {
+    if (allowEmpty) return "";
+    errors.push(`${label} must not be empty`);
+    return undefined;
+  }
+  if (value.length > max) {
+    errors.push(`${label} must be at most ${max} characters`);
+    return undefined;
+  }
+  if (!isPrintableAscii(value)) {
+    errors.push(`${label} must be printable ASCII (Foxy checkout is not Unicode-safe)`);
+    return undefined;
+  }
+  if (hasUnsafeCssChars(value)) {
+    errors.push(`${label} must not contain ; { } < or >`);
+    return undefined;
+  }
+  return value;
+}
+
+function asObject(raw: unknown): Record<string, unknown> | null {
+  return raw && typeof raw === "object" && !Array.isArray(raw)
+    ? (raw as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Validate + sanitize an untrusted checkout-style body into a complete
+ * `CheckoutStyle`. On any field error, returns every error (not just the first)
+ * so the editor can surface them together. On success, the returned style is the
+ * default with the validated overrides merged on top.
+ */
+export function validateCheckoutStyleInput(raw: unknown): CheckoutStyleInputResult {
+  const body = asObject(raw);
+  if (!body) return { ok: false, errors: ["body must be a JSON object"] };
+
+  const errors: string[] = [];
+  const override: {
+    colors?: Partial<CheckoutStyleColors>;
+    typography?: { fontFamily?: string; baseSize?: string };
+    button?: { radius?: string };
+    logoUrl?: string;
+  } = {};
+
+  const colors = asObject(body.colors);
+  if (body.colors !== undefined && !colors) {
+    errors.push("colors must be an object");
+  } else if (colors) {
+    const out: Partial<CheckoutStyleColors> = {};
+    for (const key of COLOR_KEYS) {
+      const v = takeString(colors[key], `colors.${key}`, MAX.color, errors);
+      if (v !== undefined) out[key] = v;
+    }
+    if (Object.keys(out).length > 0) override.colors = out;
+  }
+
+  const typography = asObject(body.typography);
+  if (body.typography !== undefined && !typography) {
+    errors.push("typography must be an object");
+  } else if (typography) {
+    const out: { fontFamily?: string; baseSize?: string } = {};
+    const fontFamily = takeString(typography.fontFamily, "typography.fontFamily", MAX.fontFamily, errors);
+    if (fontFamily !== undefined) out.fontFamily = fontFamily;
+    const baseSize = takeString(typography.baseSize, "typography.baseSize", MAX.length, errors);
+    if (baseSize !== undefined) out.baseSize = baseSize;
+    if (Object.keys(out).length > 0) override.typography = out;
+  }
+
+  const button = asObject(body.button);
+  if (body.button !== undefined && !button) {
+    errors.push("button must be an object");
+  } else if (button) {
+    const radius = takeString(button.radius, "button.radius", MAX.length, errors);
+    if (radius !== undefined) override.button = { radius };
+  }
+
+  // logoUrl: optional. An empty string clears it (falls back to default = none);
+  // a set value must be an absolute https URL within the length cap.
+  if (body.logoUrl !== undefined) {
+    const logo = takeString(body.logoUrl, "logoUrl", MAX.logoUrl, errors, true);
+    if (logo) {
+      if (!/^https:\/\/\S+$/.test(logo)) {
+        errors.push("logoUrl must be an absolute https URL");
+      } else {
+        override.logoUrl = logo;
+      }
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors };
+  return { ok: true, style: mergeCheckoutStyle(DEFAULT_CHECKOUT_STYLE, override) };
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Decide which tenant a checkout-style save may write to (U12b — 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
+ * "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
+ * reuses `resolveAdminTenantMode` — the SAME staff-membership/admission gate the
+ * admin shell renders the picker envelope from — so there is ONE authorization
+ * model, not a parallel one.
+ *
+ * Deny-by-default: a requested target that differs from the owner is honored only
+ * when `resolveAdminTenantMode` authorizes it (staff + a real membership or a live
+ * staff selection for that exact tenant). The merchant / own-tenant path is
+ * unchanged: no target (or a target equal to the owner) writes to the owner, with
+ * no session read required.
+ *
+ * Pure (no I/O, no Astro) — the caller supplies the already-read viewer session —
+ * so it is unit-testable in isolation.
+ */
+import { resolveAdminTenantMode } from "@/lib/adminTenantEnvelope";
+import type { SessionRecord } from "@/lib/auth/session";
+
+export type WriteTargetResult =
+  | { ok: true; targetTenant: string }
+  | { ok: false; status: number; message: string };
+
+export function resolveCheckoutStyleWriteTarget(input: {
+  /** The operator's own tenant appDomain (from resolveOwnerSession = routed tenant). */
+  owner: string;
+  /** The tenant the caller asked to write, from the request body (the picker target). */
+  requestedTarget: string | null | undefined;
+  /** The signed-in viewer session — only needed (and only read) for a cross-tenant write. */
+  session: SessionRecord | null | undefined;
+  /** Current time (epoch seconds), for the staff-selection expiry check. */
+  nowSeconds: number;
+}): WriteTargetResult {
+  const requested = (input.requestedTarget ?? "").trim();
+
+  // Merchant / own-tenant path — unchanged. No requested target, or a target that
+  // is just the operator's own tenant, writes to the owner.
+  if (!requested || requested === input.owner) {
+    return { ok: true, targetTenant: input.owner };
+  }
+
+  // Cross-tenant: authorize EXACTLY as the admin shell does. adminAppTenant is the
+  // routed tenant (the owner); a staff session with a real membership or a live
+  // staff selection for `requested` yields envelope.targetTenant === requested.
+  const mode = resolveAdminTenantMode({
+    session: input.session,
+    adminAppTenant: input.owner,
+    requestedTarget: requested,
+    nowSeconds: input.nowSeconds,
+  });
+  if (mode.deniedTarget || mode.envelope.targetTenant !== requested) {
+    return {
+      ok: false,
+      status: 403,
+      message: `not authorized to write checkout styling for tenant: ${requested}`,
+    };
+  }
+  return { ok: true, targetTenant: requested };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Canonical tenant envelope for the admin console lives in
+ * `lib/adminTenantEnvelope.ts` (admin-tenant-mode) — it carries the real
+ * 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`).
+ */
+export type { AdminTenantEnvelope } from "@/lib/adminTenantEnvelope";

package/apps/storefront/src/lib/admin/evidence/evidenceReference.ts

@@ -0,0 +1,32 @@
+/**
+ * Evidence reference model (baseline "Evidence Graph"; ai-evidence-substrate
+ * item c). A durable, typed pointer connecting the domains the baseline names:
+ * orders, customers, products, payments, verification events,
+ * fulfillment/tracking, support/contact events, policy acceptance, tax/excise
+ * evidence, and admin/user actions. `relatedRefs` is how a single reference
+ * connects across domains (e.g. an order's evidence pointing at the
+ * verification event and payment that backed it) — the "graph" edges.
+ */
+export type EvidenceKind =
+  | "order"
+  | "customer"
+  | "product"
+  | "payment"
+  | "verification_event"
+  | "fulfillment_tracking"
+  | "support_contact_event"
+  | "policy_acceptance"
+  | "tax_excise"
+  | "admin_action";
+
+export interface EvidenceReference {
+  /** Stable id for this reference, e.g. `evidence:order:#2248293823`. */
+  id: string;
+  kind: EvidenceKind;
+  /** The domain record this points at (an order id, customer id, etc.). */
+  recordId: string;
+  label: string;
+  at: string;
+  /** Other evidence reference ids this one connects to. */
+  relatedRefs: string[];
+}

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

@@ -0,0 +1,27 @@
+import type { AdminTenantEnvelope } from "./envelope";
+
+/**
+ * Per-request memoization for the pure mock view-model builders. Each builder is
+ * a pure function of `envelope.targetTenant`, but admin.astro mounts every tab on
+ * every request and several builders call one another (e.g. evidence rebuilds
+ * orders/customers/products), so a single render can rebuild the same tenant's
+ * dataset many times.
+ *
+ * The cache is keyed by the envelope OBJECT REFERENCE via a WeakMap: admin.astro
+ * constructs one envelope per request and passes that same reference to every
+ * tab, so the cache is naturally scoped to a single request and garbage-collected
+ * with the envelope. That avoids the cross-request leak a naive module-level
+ * tenant-keyed Map would cause on a warm Cloudflare Worker isolate — no manual
+ * eviction, no unbounded growth, no stale cross-tenant reuse.
+ */
+export function memoizeByEnvelope<T>(
+  compute: (envelope: AdminTenantEnvelope) => T,
+): (envelope: AdminTenantEnvelope) => T {
+  const cache = new WeakMap<AdminTenantEnvelope, T>();
+  return (envelope) => {
+    if (cache.has(envelope)) return cache.get(envelope) as T;
+    const value = compute(envelope);
+    cache.set(envelope, value);
+    return value;
+  };
+}