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

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

@@ -0,0 +1,291 @@
+/**
+ * Offline dogfood of the eight v84 nonportable-code dispositions.
+ *
+ * This module sees only reviewed, redacted dossier metadata. It can emit typed
+ * semantic events into an in-memory callback, evaluate a pure path mapping, or
+ * record an inert retirement. It has no destination, browser, renderer,
+ * persistence, network, install, publish, or source-tenant capability.
+ */
+import {
+  CONSENT_CONFIG_SCHEMA_VERSION,
+  CommerceEventBroker,
+  ManagedAnalyticsEventBrokerBridge,
+  buildTenantConsentBroker,
+  validateConsentConfig,
+  validateTenantActionRegistry,
+  type CommerceEvent,
+} from "@tot/public-runtime";
+import type {
+  V84NonportableCodeIntentDossier,
+} from "./v84NonportableCodeCoaching.js";
+import type { V84CloneMigrationEvidence } from "./v84CloneMigrationEvidence.js";
+import { assertExactV84DogfoodContract } from "./v84NonportableRouteContract.js";
+import {
+  sameV84ReplayValue,
+  type V84CleanCloneReplayContext,
+} from "./v84CleanCloneReplayContext.js";
+
+const SOURCE = "tokenoftrust.com" as const;
+const CLONE = "tokenoftrust.com~clone~gtm-migration-v84" as const;
+const AT = "2026-08-30T00:00:00.000Z";
+const CORRELATION = { id: "corr-v84-nonportable-dogfood", expiresAt: "2026-08-30T02:00:00.000Z" };
+const PROTECTED = ["admin", "account", "identity", "age-assurance", "checkout", "payment"] as const;
+
+export type V84DogfoodOutcome = "converted" | "retired" | "evidence-rejected";
+
+export interface V84DogfoodLedgerRow {
+  readonly identity: string;
+  readonly intent: string;
+  readonly route: string;
+  readonly attemptedSteps: readonly string[];
+  readonly artifact: Readonly<Record<string, unknown>>;
+  readonly expectedVersusActual: { readonly expected: string; readonly actual: string };
+  readonly testsAndCloneQa: readonly string[];
+  readonly rollbackProof: string;
+  readonly finalOutcome: V84DogfoodOutcome;
+  readonly productRunbookGap: string | null;
+}
+
+function consentBroker() {
+  const checked = validateConsentConfig({
+    schemaVersion: CONSENT_CONFIG_SCHEMA_VERSION,
+    purposes: [{ purpose: "analytics", legalBasis: "consent", defaultState: "denied" }],
+    cmp: { mode: "none" },
+  });
+  if (!checked.ok) throw new Error("The fixed local consent policy is invalid.");
+  const broker = buildTenantConsentBroker(checked.value);
+  broker.setDecisions({ analytics: "granted" });
+  return broker;
+}
+
+function vendorAdapterId(dossier: V84NonportableCodeIntentDossier): string {
+  const ids: Readonly<Record<string, string>> = {
+    "tag:4": "platform.hubspot",
+    "tag:18": "platform.capterra",
+    "tag:29": "platform.linkedin",
+    "tag:31": "platform.g2",
+  };
+  const adapterId = ids[dossier.sourceObject.nodeKey];
+  if (!adapterId) throw new Error("The vendor destination route is not reviewed.");
+  return adapterId;
+}
+
+function exerciseNativeHook(dossier: V84NonportableCodeIntentDossier) {
+  const catalogLookup = { adapterId: vendorAdapterId(dossier), found: false } as const;
+  if (dossier.requiredContract.actionSelection === "owner-selection-required") {
+    return {
+      kind: "native-contract-refusal",
+      hook: dossier.recommendedTotPort.nativeHook,
+      approvedChoices: [...dossier.requiredContract.approvedActionNames],
+      deliveryCount: 0,
+      reason: "owner-action-selection-required",
+      catalogLookup,
+    } as const;
+  }
+  const registry = validateTenantActionRegistry({
+    schemaVersion: 1,
+    actions: dossier.requiredContract.approvedActionNames.map((name) => ({ name })),
+  });
+  if (!registry.ok) throw new Error("The dossier action contract is invalid.");
+  const consent = consentBroker();
+  const delivered: CommerceEvent[] = [];
+  const broker = new CommerceEventBroker({
+    trusted: { tenant: CLONE, environment: "candidate", siteSurface: "marketing" },
+    source: `urn:tot:storefront:v84-dogfood:${dossier.dossierId}`,
+    consentSnapshot: () => consent.getSnapshot(),
+    tenantActionRegistry: registry.value,
+    now: () => AT,
+  });
+  broker.subscribe({
+    id: `fake-local-${dossier.dossierId}`,
+    consentPurpose: "analytics",
+    types: dossier.recommendedTotPort.nativeHook ? [dossier.recommendedTotPort.nativeHook] : [],
+    sink: { kind: "callback", handler: (event) => delivered.push(event) },
+  });
+  const bridge = new ManagedAnalyticsEventBrokerBridge({ broker });
+  let results;
+  if (dossier.recommendedTotPort.nativeHook === "storefront.action.activated.v1") {
+    const initialized = bridge.initialize({ logicalId: `${dossier.dossierId}-document`, path: "/v84-dogfood", correlation: CORRELATION });
+    if (!initialized.ok || !initialized.emitted) throw new Error("The local action bridge did not initialize safely.");
+    results = dossier.requiredContract.approvedActionNames.map((name, index) =>
+      bridge.activate({ logicalId: `${dossier.dossierId}-action-${index + 1}`, name, correlation: CORRELATION }));
+  } else {
+    results = [bridge.initialize({ logicalId: dossier.dossierId, path: "/v84-dogfood", correlation: CORRELATION })];
+  }
+  bridge.dispose();
+  if (results.some((result) => !result.ok || !result.emitted) || delivered.length !== results.length) {
+    throw new Error("The local native-hook exercise did not deliver the exact typed event set.");
+  }
+  if (delivered.some((event) => event.storefront.tenant !== CLONE || event.storefront.environment === "live")) {
+    throw new Error("The local native-hook exercise escaped the diagnostic clone.");
+  }
+  return {
+    kind: "in-memory-native-event-proof",
+    hook: delivered[0]?.type,
+    payloads: delivered.map((event) => event.data),
+    payloadKeys: [...new Set(delivered.flatMap((event) => Object.keys(event.data)))].sort(),
+    deliveryCount: delivered.length,
+    destination: "fake-local-callback",
+    disposed: true,
+    catalogLookup,
+  } as const;
+}
+
+function retire(dossier: V84NonportableCodeIntentDossier, replayContext?: V84CleanCloneReplayContext) {
+  if (dossier.recommendedTotPort.nativeHook !== null) {
+    throw new Error("A retirement dossier unexpectedly requested runtime authority.");
+  }
+  const cloneLocalMarkers = new Set<string>();
+  const marker = `${CLONE}:retired:${dossier.sourceObject.nodeKey}`;
+  const markerKey = `stage/dogfood/retirement/${dossier.sourceObject.nodeKey}`;
+  if (replayContext) replayContext.write(markerKey, marker);
+  else cloneLocalMarkers.add(marker);
+  const markerObserved = replayContext
+    ? replayContext.read<string>(markerKey) === marker
+    : cloneLocalMarkers.has(marker);
+  if (replayContext) replayContext.delete(markerKey);
+  else cloneLocalMarkers.delete(marker);
+  const markerRemoved = replayContext
+    ? replayContext.read<string>(markerKey) === undefined
+    : !cloneLocalMarkers.has(marker);
+  if (!markerObserved || !markerRemoved) throw new Error("The inert retirement marker was not reversible.");
+  return {
+    kind: "inert-retirement-record",
+    retained: { nodeKey: dossier.sourceObject.nodeKey, dossierId: dossier.dossierId },
+    runtimeAuthority: "none",
+    installCreated: false,
+    markerObserved,
+    markerRemoved,
+  } as const;
+}
+
+function rejectedGap(dossier: V84NonportableCodeIntentDossier): string {
+  if (dossier.sourceObject.nodeKey === "variable:38") {
+    return "consumer decision required: name the consumer and approve a closed output enum before conversion";
+  }
+  const gap = dossier.recommendedTotPort.owningProductGap;
+  if (!gap) throw new Error("A non-retirement route lacks an exact owning-product gap.");
+  const ownerGap = dossier.requiredContract.actionSelection === "owner-selection-required"
+    ? "; consumer owner must select one approved action name"
+    : "";
+  return `owning product capability unavailable: ${gap}${ownerGap}`;
+}
+
+function exercise(
+  dossier: V84NonportableCodeIntentDossier,
+  replayContext?: V84CleanCloneReplayContext,
+): V84DogfoodLedgerRow {
+  if (dossier.recommendedTotPort.route === "retire") {
+    return {
+      identity: dossier.sourceObject.nodeKey,
+      intent: dossier.recoveredBusinessIntent,
+      route: "retire",
+      attemptedSteps: ["matched the exact redacted identity and graph role", "asserted no native hook", "created and observed a clone-local inert marker", "removed the marker"],
+      artifact: retire(dossier, replayContext),
+      expectedVersusActual: {
+        expected: "retain audit identity with zero runtime behavior",
+        actual: "inert retirement recorded; no install, hook, destination, or runtime authority created",
+      },
+      testsAndCloneQa: ["identity accounted once", "dependency graph checked", "marker observed then removed", "no hook requested", "clone effect counters remain zero"],
+      rollbackProof: "No runtime state exists to restore; removing the inert record leaves behavior unchanged.",
+      finalOutcome: "retired",
+      productRunbookGap: null,
+    };
+  }
+  const isMapping = dossier.recommendedTotPort.route === "declarative-typed-mapping";
+  const artifact = isMapping ? {
+    kind: "declarative-conversion-refusal",
+    observedGraph: { consumer: "trigger:39", variable: "variable:38", consumingTagCount: 0 },
+    mappingCreated: false,
+    reason: "named-consumer-and-output-enum-unresolved",
+  } as const : exerciseNativeHook(dossier);
+  const gap = rejectedGap(dossier);
+  return {
+    identity: dossier.sourceObject.nodeKey,
+    intent: dossier.recoveredBusinessIntent,
+    route: dossier.recommendedTotPort.route,
+    attemptedSteps: isMapping
+      ? ["verified trigger:39 references variable:38", "verified no tag consumes trigger:39", "looked for a named consumer and approved output enum", "refused to invent a mapping"]
+      : dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? ["validated the closed action choice set", "refused to choose for the owner", "confirmed zero delivery", "looked up the owned destination"]
+        : ["validated the closed native event contract", "granted local analytics consent", "delivered the exact typed event set to an in-memory callback", "disposed the bridge", "looked up the owned destination"],
+    artifact,
+    expectedVersusActual: {
+      expected: dossier.recommendedTotPort.saferAlternative,
+      actual: dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? `closed choice set validated with zero emission; exercise stopped: ${gap}`
+        : isMapping
+          ? `no mapping was created; exercise stopped: ${gap}`
+          : `safe local native contract exercise passed, but conversion stopped: ${gap}`,
+    },
+    testsAndCloneQa: isMapping
+      ? ["exact graph edge is present", "consumer tag count is zero", "no mapping or destination effect exists"]
+      : dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? ["all approved choices retained", "zero events emitted before owner selection", "managed vendor adapter absent"]
+        : ["typed payload set delivered exactly once each", "clone tenant and candidate environment pinned", "fake callback disposed", "protected surfaces excluded"],
+    rollbackProof: isMapping
+      ? "Discarding the refusal artifact leaves the prior no-mapping state unchanged; no consumer was connected."
+      : dossier.requiredContract.actionSelection === "owner-selection-required"
+        ? "No subscriber, event, install, or destination state was created before the required owner decision."
+        : "Disposal removes the only in-memory subscriber; no install or destination state exists.",
+    finalOutcome: "evidence-rejected",
+    productRunbookGap: gap,
+  };
+}
+
+/** Exercise every reviewed route and return a terminal eight-row ledger. */
+export function buildV84NonportableRouteDogfood(
+  evidence: V84CloneMigrationEvidence,
+  catalogAdapterIds: readonly string[],
+  replayContext?: V84CleanCloneReplayContext,
+) {
+  if (replayContext && !sameV84ReplayValue(
+    replayContext.read<V84CloneMigrationEvidence>("stage/import/handoff"),
+    evidence,
+  )) {
+    throw new Error("The dogfood proof did not receive the shared import handoff.");
+  }
+  const safe = assertExactV84DogfoodContract(evidence, catalogAdapterIds);
+  const coaching = safe.evidence.nonportableCodeCoaching;
+  if (!coaching.policy.sourceReadOnly || !coaching.policy.importedArtifactsInert || coaching.policy.installsOrPublishes) {
+    throw new Error("The coaching policy is outside the inert diagnostic scope.");
+  }
+  if (coaching.dossiers.length !== 8 || new Set(coaching.dossiers.map((item) => item.sourceObject.nodeKey)).size !== 8) {
+    throw new Error("The dogfood gate requires exactly eight unique dossiers.");
+  }
+  if (coaching.dossiers.some((item) => item.recommendedTotPort.status !== "not-installed")) {
+    throw new Error("The dogfood input must be the reviewed pre-install coaching state.");
+  }
+  const ledger = coaching.dossiers.map((dossier) => exercise(dossier, replayContext));
+  if (ledger.some((row) => !["converted", "retired", "evidence-rejected"].includes(row.finalOutcome))) {
+    throw new Error("Every dogfood route must end in an explicit terminal outcome.");
+  }
+  const result = {
+    schemaVersion: 1 as const,
+    scope: { sourceTenant: SOURCE, sourceMode: "read-only-fixture" as const, cloneTenant: CLONE, destinationMode: "fake-local-only" as const },
+    ledger,
+    summary: {
+      total: ledger.length,
+      converted: ledger.filter((row) => row.finalOutcome === "converted").length,
+      retired: ledger.filter((row) => row.finalOutcome === "retired").length,
+      evidenceRejected: ledger.filter((row) => row.finalOutcome === "evidence-rejected").length,
+      unexplainedNotInstalled: 0,
+    },
+    catalogLookup: {
+      presentAdapterIds: [...safe.catalogAdapterIds].sort(),
+      requestedVendorAdapterIds: ["platform.hubspot", "platform.capterra", "platform.linkedin", "platform.g2"],
+      missingVendorAdapterIds: ["platform.hubspot", "platform.capterra", "platform.linkedin", "platform.g2"],
+    },
+    safety: {
+      sourceReads: 0, sourceWrites: 0, clonePersistentWrites: 0, externalNetworkRequests: 0,
+      liveSecretsUsed: 0, productionActions: 0, importedCodeExecuted: false,
+      originalMarkupRendered: false, runtimeLoaderInitialized: false, dataLayerTouched: false,
+    },
+    protectedSurfaces: [...PROTECTED],
+  };
+  if (replayContext) {
+    for (const row of ledger) replayContext.write(`stage/dogfood/artifacts/${row.identity}`, row.artifact);
+    replayContext.write("stage/dogfood/handoff", result);
+  }
+  return result;
+}

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

@@ -0,0 +1,95 @@
+/**
+ * The EDGE transport for the pinned managed-analytics v1 contract: a thin HTTP
+ * adapter that satisfies {@link Ws1ManagedAnalyticsClient} by POSTing each
+ * pinned request to WS1's lifecycle service and returning the pinned response
+ * shape. WS1 owns the actual service; this file only carries the request over
+ * the wire.
+ *
+ * Tenant authority is server-derived, exactly as the pinned contract demands
+ * ("no request in this module accepts a tenant id"): the tenant is sent as a
+ * server-to-server header alongside the service credential — NEVER in a request
+ * body, and NEVER read from the caller's request body. Unconfigured service URL
+ * -> `null` (the route answers 503), never a guess.
+ */
+import type { APIContext } from "astro";
+import {
+  MANAGED_ANALYTICS_API_V1_VERSION_POLICY,
+  type CreateMigrationDraftRequest,
+  type CreateMigrationDraftResponse,
+} from "@tot/public-runtime";
+import { readEnv } from "../env.js";
+import type { Ws1ManagedAnalyticsClient } from "./gtmMigrationInstall.js";
+
+export interface Ws1ManagedAnalyticsMigrationClient extends Ws1ManagedAnalyticsClient {
+  createMigrationDraft(request: CreateMigrationDraftRequest): Promise<CreateMigrationDraftResponse>;
+}
+
+export type Ws1Fetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+/** Base URL of WS1's managed-analytics lifecycle service (scheme + host). */
+const SERVICE_URL_ENV = "MANAGED_ANALYTICS_API_URL";
+/** Server-to-server bearer credential for WS1 (scopes the tenant server-side). */
+const SERVICE_SECRET_ENV = "MANAGED_ANALYTICS_API_SECRET";
+
+/** The versioned base path, taken from the pinned version policy — never hard-coded twice. */
+const V1_PATH = MANAGED_ANALYTICS_API_V1_VERSION_POLICY.path;
+
+/** POST one pinned request to `<base><v1>/<operation>` and return the parsed pinned response. */
+function post<TReq, TRes>(
+  fetchImpl: Ws1Fetch,
+  baseUrl: string,
+  operation: string,
+  headers: Record<string, string>,
+): (request: TReq) => Promise<TRes> {
+  return async (request: TReq): Promise<TRes> => {
+    const res = await fetchImpl(`${baseUrl}${V1_PATH}/${operation}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(request),
+    });
+    // WS1 returns the pinned success OR error envelope as JSON for every status.
+    return (await res.json()) as TRes;
+  };
+}
+
+/** Build the tenant-bound public WS1 HTTP client; tests may inject a no-network fetch. */
+export function createWs1ManagedAnalyticsClient(input: {
+  readonly baseUrl: string;
+  readonly tenantId: string;
+  readonly authorization?: string;
+  readonly fetchImpl?: Ws1Fetch;
+}): Ws1ManagedAnalyticsMigrationClient {
+  const baseUrl = input.baseUrl.replace(/\/$/, "");
+  const headers: Record<string, string> = { "x-tot-tenant": input.tenantId };
+  if (input.authorization) headers.authorization = input.authorization;
+  const fetchImpl = input.fetchImpl ?? fetch;
+  return {
+    getMigrationDraft: post(fetchImpl, baseUrl, "getMigrationDraft", headers),
+    createMigrationDraft: post(fetchImpl, baseUrl, "createMigrationDraft", headers),
+    getAdapterDefinition: post(fetchImpl, baseUrl, "getAdapterDefinition", headers),
+    getIntegrationInstall: post(fetchImpl, baseUrl, "getIntegrationInstall", headers),
+    createIntegrationInstall: post(fetchImpl, baseUrl, "createIntegrationInstall", headers),
+    reviseIntegrationInstall: post(fetchImpl, baseUrl, "reviseIntegrationInstall", headers),
+  };
+}
+
+/**
+ * Build an HTTP-backed {@link Ws1ManagedAnalyticsClient} for `tenantId`, or
+ * `null` when WS1's service URL isn't configured in this runtime. `tenantId`
+ * comes from the resolved operator session — never the request body — and is
+ * sent as a server-to-server header, keeping every request body tenant-free per
+ * the pinned contract.
+ */
+export async function resolveWs1ManagedAnalyticsClient(
+  _context: APIContext,
+  tenantId: string,
+): Promise<Ws1ManagedAnalyticsClient | null> {
+  const baseUrl = (await readEnv(SERVICE_URL_ENV))?.replace(/\/$/, "");
+  if (!baseUrl) return null;
+  const secret = await readEnv(SERVICE_SECRET_ENV);
+  return createWs1ManagedAnalyticsClient({
+    baseUrl,
+    tenantId,
+    ...(secret ? { authorization: `Bearer ${secret}` } : {}),
+  });
+}

package/apps/storefront/src/lib/auth/adminApiGuard.ts

@@ -0,0 +1,66 @@
+/**
+ * Fail-closed access guard for tenant-scoped admin APIs (`/api/admin/**`).
+ *
+ * The admin JSON routes must NOT trust the ambient login gate for their auth:
+ * that gate is conditional (`DEMO_GATE_MODE="login"` on a gated host), so a route
+ * that leans on it is wide open on any non-gated host. This guard makes each
+ * admin API validate the caller EXPLICITLY, bound to the Host-resolved tenant
+ * (`locals.tenant.appDomain` — never a client value, never a default), and
+ * deny-closed on absence:
+ *
+ *   no session                        → 401 sign_in_required
+ *   session, but no standing for THIS tenant → 403 not_authorized
+ *   member/owner (or staff) of THIS tenant   → allowed, entry returned
+ *
+ * The decision core is PURE (unit-testable); `requireAdminApiEntry` is the thin
+ * Astro/I-O wrapper the routes call.
+ */
+import type { APIContext } from "astro";
+import { readViewerSession } from "@/lib/auth/route";
+import { resolveAdminEntry, type AdminEntryDecision } from "@/lib/auth/adminEntry";
+import type { SessionRecord } from "./session.js";
+
+export type AdminApiAccess =
+  | { ok: true; entry: AdminEntryDecision }
+  | { ok: false; status: 401 | 403; reason: "sign_in_required" | "not_authorized" };
+
+/**
+ * PURE fail-closed decision for a tenant-scoped admin API caller.
+ *
+ * @param requireOwner when true, only an owner/admin viewer OR a ToT-staff viewer
+ *   passes (a plain team member is refused) — for routes that mutate/expose
+ *   owner-level operational surfaces. Default (false) admits any member/owner/staff
+ *   of the tenant, matching who reaches the admin shell.
+ */
+export function decideAdminApiAccess(input: {
+  record: SessionRecord | null | undefined;
+  hostResource: string;
+  nowSeconds: number;
+  requireOwner?: boolean;
+}): AdminApiAccess {
+  const { record, hostResource, nowSeconds, requireOwner } = input;
+  if (!record) return { ok: false, status: 401, reason: "sign_in_required" };
+
+  const entry = resolveAdminEntry({ record, hostResource, nowSeconds });
+  const staffScope = Array.isArray(record.staff) && record.staff.length > 0;
+  const authorized = requireOwner
+    ? entry.isOwnerViewer || staffScope
+    : entry.admitted;
+  if (!authorized) return { ok: false, status: 403, reason: "not_authorized" };
+
+  return { ok: true, entry };
+}
+
+/** Astro wrapper: read the viewer session and decide, bound to the routed tenant. */
+export async function requireAdminApiEntry(
+  context: APIContext,
+  opts?: { requireOwner?: boolean },
+): Promise<AdminApiAccess> {
+  const record = await readViewerSession(context);
+  return decideAdminApiAccess({
+    record,
+    hostResource: context.locals.tenant?.appDomain ?? "",
+    nowSeconds: Math.floor(Date.now() / 1000),
+    requireOwner: opts?.requireOwner,
+  });
+}

package/apps/storefront/src/lib/auth/adminEntry.ts

@@ -30,11 +30,11 @@
  */
 import type { SessionRecord } from "./session.js";
 import { sessionHostCapability } from "./loginGate.js";
-import { decideIsOwner } from "@/lib/change/route";
+import { decideIsOwner } from "@/lib/change/route/route";
 import {
   resolveShipCapabilities,
   type ShipCapabilities,
-} from "@/lib/change/shipCapabilities";
+} from "@/lib/change/route/ship-capabilities";
 import type { Capability } from "@/lib/change/types";
 import { OWNER_CAPABILITIES } from "@/lib/grants/session";
 

package/apps/storefront/src/lib/auth/adminLanding.ts

@@ -0,0 +1,88 @@
+/**
+ * Canonical admin tenant-landing decision (pure).
+ *
+ * The admin console is Host-routed: each tenant's admin lives at that tenant's
+ * host (or the DNS-free `/<tenant>/admin` path form). "Which tenant" is therefore
+ * carried by the URL, never inferred from an ambient global. The ambiguity this
+ * module resolves is the ONE case the URL alone can't settle: an authenticated
+ * viewer who lands on the admin of a tenant they are NOT a member of — because
+ * they followed a stale/shared deep link, or the host fell back to the registry
+ * default tenant. The wrong answers are (a) bounce them to /auth/login even though
+ * they hold a valid session (a sign-in loop), or (b) silently show them the wrong
+ * tenant's data. The canonical answer:
+ *
+ *   - member/owner/staff of the routed tenant → ENTER (render admin here).
+ *   - no session                             → LOGIN (gate, `next` preserved).
+ *   - authed, not here, exactly ONE tenant   → AUTO (their sole tenant's /admin).
+ *   - authed, not here, zero OR many tenants → SELECT (the /admin/select picker;
+ *                                               the page differentiates 0 vs many).
+ *
+ * PURE (no I/O, no Astro): it COMPOSES `sessionAdmitsHost` (the host-bound
+ * admission the middleware gate already uses) and `selectTenant` (the vendor
+ * single-vs-picker rule) so the console, the gate, and this landing can never
+ * drift on "does this viewer belong to this tenant". Unit-testable in isolation.
+ */
+import type { SessionRecord } from "./session.js";
+import { sessionAdmitsHost } from "./loginGate.js";
+import { safeNext } from "./route.js";
+import { selectTenant } from "@/lib/dashboard/tenantSelection";
+
+/** The tenant-selection surface, in both host-routed and tenant-first path forms. */
+export function isAdminSelectPath(pathname: string): boolean {
+  if (pathname === "/admin/select") return true;
+  return /^\/[^/]+\/admin\/select$/.test(pathname);
+}
+
+/**
+ * The DNS-free path-form URL of a tenant's admin on the current host. A leading
+ * `/<resource>/` segment middleware-selects that tenant regardless of which host
+ * the request arrived on, so this reaches ANOTHER tenant's admin from here.
+ */
+export function adminUrlForTenant(resource: string): string {
+  return `/${resource.trim()}/admin`;
+}
+
+export type AdminLanding =
+  | { action: "enter" }
+  | { action: "login"; location: string }
+  | { action: "auto"; location: string }
+  | { action: "select"; location: string };
+
+export interface AdminLandingInput {
+  /** The viewer's full session (all memberships), or null when unauthenticated. */
+  record: SessionRecord | null | undefined;
+  /** The Host-resolved tenant's appDomain (server-derived, never client input). */
+  routedTenant: string;
+  /** locals.basePath: "" (host-form) or "/<domain>" (tenant-first path form). */
+  basePath: string;
+  /** The intended admin destination (`pathname + search`), preserved as `next`. */
+  intended: string;
+  /** Epoch seconds, for the staff-selection expiry check. */
+  nowSeconds: number;
+}
+
+export function resolveAdminLanding(input: AdminLandingInput): AdminLanding {
+  const { record, routedTenant, basePath, intended, nowSeconds } = input;
+
+  if (!record) {
+    const next = encodeURIComponent(safeNext(intended));
+    return { action: "login", location: `/auth/login?next=${next}` };
+  }
+
+  // Member/owner of the routed tenant, or a ToT-staff viewer → this IS their
+  // admin context. Identical admission to the middleware gate, by construction.
+  if (sessionAdmitsHost(record, routedTenant, nowSeconds)) {
+    return { action: "enter" };
+  }
+
+  // Authenticated, but with no standing for the routed tenant. Route them to
+  // their OWN tenant(s) rather than the wrong one or a sign-in loop. A sole
+  // membership auto-selects; zero or several go to the picker (which honestly
+  // renders "nothing to manage" for zero).
+  const selection = selectTenant(record.tenants);
+  const selectLocation = `${basePath || ""}/admin/select`;
+  if (selection.mode === "single") {
+    return { action: "auto", location: adminUrlForTenant(selection.tenant.resource) };
+  }
+  return { action: "select", location: selectLocation };
+}