fix(compose): mount guards are framework-supplied beforeLoads (#825)

* fix(compose): mount guards are framework-supplied beforeLoads — client-rendered loads resolve the session (#818)

On a client-rendered full page load the root context's session is still
unresolved when the mount gates ran, so they read a signed-in visitor as
signed out — authed pages bounced through /login, and an admin reloading
/admin landed on /dashboard.

The mount registry no longer declares gate kinds. Each mount carries
shape metadata (guarded, implemented), and constructTree takes guards —
ordinary beforeLoads keyed by mount id — supplied by the composing
framework; construction fails loudly when a guarded mount has none. The
default wiring guards authenticated with requireSession and admin with
requireAdmin, so guards resolve through the session query cache (SSR
cache-hit, client-rendered one cached fetch) and inherit the auth policy
— tri-state reads, banned handling, login redirects with the return
path — from one place. The engine loses its last auth semantics:
HostContext, GateUser, /login, and role checks are gone.

Co-authored-by: adenarc <334235131+adenarc@users.noreply.github.com>

* fix(compose): standalone-clean guard wiring — session-cache split from the auth client; CSR spec drops the anonymous logout jar

CI on #825 caught two defects in the new surface:

1. The shim's static edge into auth-guards dragged the better-auth client
   (@better-auth/api-key) into everything-dev/ui/manifest, and the
   standalone tarball install could not resolve it. The session-cache
   primitives (sessionQueryKey, sessionQueryOptions, refreshSessionCache)
   move to ui/auth-session — type-only imports, no runtime deps — and
   auth.ts re-exports them; auth-guards consumes the dependency-free
   module, so the manifest surface imports clean.

2. csr-guarded-reload's signed-out case injected the "logout" cookie
   jar, which is an anonymous signed-in session — requireSession passes
   and requireAdmin redirects to /dashboard. Signed-out is no cookies at
   all; the test now asserts /admin → /login?redirect=%2Fadmin on a
   fresh context.

* fix(compose): guard wiring moves to the core ui's composition entry — ui/manifest is standalone again

The standalone-install gate failure was a layering signal, not a
packaging problem: the shim put the app's auth policy inside the generic
composition surface, which must import with only everything-dev's
declared dependencies (it is what the host consumes). Both attempted
workarounds — a dependency-free auth-session split, then a dynamic
import — patched policy living in the wrong layer.

The wiring now lives where the core ui composes itself, where the auth
client is already present: a new everything-dev/ui/compose entry (the
engine plus the default guards) consumed by the client boot (hydrate)
and the ./compose expose the host loads for SSR (compose.gen template).
ui/manifest returns to main's pure re-export byte-for-byte, the
auth-session split is reverted (auth.ts is the only auth module), and
the standalone gate passes by construction.

* fix(compose): the compose entry exports only constructTree — template sources engine constants from ui/manifest

tsdown treeshake dropped the re-exported external bindings
(CORE_UI_PLUGIN_KEY, ComposePayloadSchema) from dist/ui/compose.mjs, so
every consumer that builds against dist (the ui container) failed
ESModulesLinkingError while typecheck passed — it resolves the
development condition against src. Verified the fix against both
resolution conditions: dist entries node-imported with asserted export
keys, and the host suite whose setup builds the ui container.

CORE_UI_PLUGIN_KEY and ComposePayloadSchema are engine vocabulary and
stay on ui/manifest; everything-dev/ui/compose exports the wired
constructTree, which is what it is.

---------

Co-authored-by: adenarc <334235131+adenarc@users.noreply.github.com>

Author: elliotBraem

.changeset/mount-guards.md

@@ -0,0 +1,6 @@
+---
+"every-plugin": patch
+"everything-dev": patch
+---
+
+Mount guards are ordinary beforeLoads supplied by the composing framework, replacing gate kinds. The mount registry now carries shape metadata only (`guarded`, `implemented`) and `constructTree` takes `guards` keyed by mount id — construction fails loudly when a guarded mount has none. The default wiring guards `authenticated` with `requireSession` and `admin` with `requireAdmin`, so a client-rendered full page load resolves the session through the query cache instead of reading a signed-in visitor as signed out (#818): full loads of authed pages no longer bounce through `/login`, and admin pages keep the `?redirect=` return path. Banned users now bounce at the mount, and signed-in non-admins on admin mounts land on `/dashboard`. The engine's invented `HostContext`/`GateUser` types are gone — it has no auth semantics.

docs/adr/0008-manifest-composition.md

@@ -52,3 +52,7 @@ Investigation (2026-09) found the framework itself converging on the same substr
 - `MOUNT_REGISTRY_VERSION` bumps; all compose digests invalidate once.
 - Plan 025 (landing carve-out) executes manifest-first as the second production consumer; plan 026 (shell into host) simplifies — the host constructs all routes, in-process or manifest-fed, one construction story; plan 028 (`app.ts`) absorbs a stable manifest-only plugin shape.
 - `bos types gen` gains merged route-type emission from manifests (typed cross-plugin `<Link>`) — replaces the `pluginPath` seam.
+
+## Amendment (2026-11): mount guards are beforeLoads, not gate kinds
+
+The registry no longer declares gate kinds (`none`/`session`/`admin`/`organization`/`team`) — each mount carries shape metadata only (`guarded`, `implemented`). Guard implementations are ordinary `beforeLoad`s supplied by the composing framework via `ConstructInput.guards`, keyed by mount id; the engine composes guard-then-declared and fails construction loudly when a `guarded` mount has no guard. The engine becomes fully auth-agnostic (no `/login`, no user/role knowledge); session semantics — tri-state query-cache reads (#527/#689), banned handling, login redirects — live in the framework glue and ride the same guards apps author in their own route files. `HostContext`/`GateUser` are deleted; the engine↔glue contract is TanStack's own `beforeLoad` shape. `MOUNT_REGISTRY_VERSION` bumps to 6; compose digests invalidate once (as the bump exists to do).

host/tests/integration/ui-compose-auth-tree.test.ts

@@ -76,6 +76,7 @@ describe("constructTree over the auth route shape", () => {
         { key: "ui", mfName: "ui" },
         { key: "auth", mfName: "auth-ui" },
       ],
+      guards: { authenticated: async () => undefined, admin: async () => undefined },
       resolve: async (ref) => {
         if (ref.key === "ui")
           return { key: "ui", manifest: CORE_MANIFEST, routeConfig: coreRouteConfig };

packages/every-plugin/src/build/ui/stubs.ts

@@ -65,19 +65,14 @@ export type {
   ConstructedTree,
   ConstructInput,
   ConstructPluginRef,
-  GateUser,
-  HostContext,
   NavManifest,
   PluginManifest,
   ResolvedPlugin,
   RouteConfigModule,
   RouteOptionsBundle,
 } from "everything-dev/ui/manifest";
-export {
-  CORE_UI_PLUGIN_KEY,
-  ComposePayloadSchema,
-  constructTree,
-} from "everything-dev/ui/manifest";
+export { CORE_UI_PLUGIN_KEY, ComposePayloadSchema } from "everything-dev/ui/manifest";
+export { constructTree } from "everything-dev/ui/compose";
 `,
   "src/globals.gen.ts": `// GENERATED FILE — do not edit. Regenerated from the installed framework version
 // by \`bos dev\` / \`bos build\` / \`bos typecheck\` (gitignored).

packages/every-plugin/src/ui/manifest/construct.ts

@@ -1,19 +1,20 @@
 import type { AnyRoute } from "@tanstack/react-router";
-import { createRootRoute, createRoute, Outlet, redirect } from "@tanstack/react-router";
+import { createRootRoute, createRoute, Outlet } from "@tanstack/react-router";
 import { CORE_UI_PLUGIN_KEY } from "./contract";
 import { digestOf } from "./descriptor";
 import type { PluginManifest, RouteRecord } from "./manifest-schema";
-import { MOUNT_REGISTRY, type MountDef, type MountId, resolveMountSegment } from "./mount-registry";
+import { MOUNT_REGISTRY, type MountId, resolveMountSegment } from "./mount-registry";
 import { compareNavItems, type NavDeclaration, type NavItem, type NavManifest } from "./nav";
 import { ROUTE_OPTION_KEYS, type RouteConfigModule, type RouteOptionsBundle } from "./route-config";
 
 /**
  * Host-side route-graph construction (ADR 0008 §1): manifests + route
  * configs in → host-built tree out. The host constructs ITS OWN Route
  * objects from validated manifest data via public `createRoute` APIs; no
- * foreign route object is ever mutated. Gates are attached HOST-side from
- * the mount registry — plugins cannot ship a route that escapes its
- * mount's gate because plugins never construct route objects.
+ * foreign route object is ever mutated. Mount guards are ordinary
+ * beforeLoads attached HOST-side from ConstructInput.guards — plugins
+ * cannot ship a route that escapes its mount's guard because plugins never
+ * construct route objects.
  *
  * Mounts are the ONLY cross-source parenting points: a root-level
  * pathless layout file (`_public.tsx`) declares the mount for the whole
@@ -34,57 +35,6 @@ function toAnyRoute(route: unknown): AnyRoute {
   return route as AnyRoute;
 }
 
-export interface GateUser {
-  id: string;
-  name?: string;
-  /** Better Auth user role — "admin" gates the admin mount. */
-  role?: string;
-}
-
-export interface HostContext {
-  user?: GateUser;
-  session?: { user?: GateUser };
-}
-
-type GateFn = (args: {
-  context: HostContext;
-  location: { pathname: string; searchStr: string };
-}) => void;
-
-/**
- * Gate redirects are absolute: gates attach to root-level mount routes, and
- * relatives would silently shift if a mount ever moved deeper in the tree.
- * The login surface is plugin-owned, never core-known.
- */
-const LOGIN_TO: string = "/login";
-const HOME_TO: string = "/";
-
-/**
- * Gate implementations by mount gate kind. Only `session` and `admin` are
- * implemented (ADR 0008 §3); unimplemented mounts are rejected during mount
- * declaration before any gate lookup, and gates are optional by type — a
- * mount without an entry (or `none`) renders ungated.
- */
-const GATES: Partial<Record<MountDef["gate"], GateFn>> = {
-  session: ({ context, location }) => {
-    const user = userOf(context);
-    if (!user) {
-      throw redirect({
-        to: LOGIN_TO,
-        search: { redirect: location.pathname + location.searchStr } as never,
-      });
-    }
-  },
-  admin: ({ context }) => {
-    const user = userOf(context);
-    if (!user) throw redirect({ to: LOGIN_TO });
-    if (user.role !== "admin") throw redirect({ to: HOME_TO });
-  },
-};
-
-const userOf = (context: HostContext | undefined): GateUser | undefined =>
-  context?.user ?? context?.session?.user;
-
 export interface ConstructPluginRef {
   /** composition identity — plugin key; participates in the digest */
   key: string;
@@ -104,6 +54,8 @@ export interface ConstructInput {
   resolve: (ref: ConstructPluginRef) => Promise<ResolvedPlugin>;
   /** core ui `__root` options — component/error/notFound + head baseline */
   rootOptions?: RouteOptionsBundle;
+  /** Guard per mount id — beforeLoads supplied by the composing framework. */
+  guards?: Partial<Record<MountId, RouteOptionsBundle["beforeLoad"]>>;
 }
 
 export interface ConstructedTree {
@@ -139,17 +91,17 @@ const navOf = (options: RouteOptionsBundle): NavDeclaration | undefined => {
 };
 
 /** Layout routes (mount or pathless) pass their authored options through,
- * like every other route kind. On mount routes the registry gate composes
+ * like every other route kind. On mount routes the mount's guard composes
  * BEFORE the declaration's own beforeLoad so a source can never escape its
- * mount's gate (ADR 0008 §3), while the declaration's return value still
+ * mount's guard (ADR 0008 §3), while the declaration's return value still
  * flows to children as route context. */
 function layoutBeforeLoad(
-  gate: GateFn | undefined,
+  guard: RouteOptionsBundle["beforeLoad"],
   declared: RouteOptionsBundle["beforeLoad"],
 ): RouteOptionsBundle["beforeLoad"] {
-  if (!gate) return declared;
-  return (args) => {
-    gate(args);
+  if (!guard) return declared;
+  return async (args) => {
+    await guard(args);
     return declared?.(args);
   };
 }
@@ -270,13 +222,16 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
     const declaration = declarations.get(mountId);
     if (!declaration) continue;
     const def = MOUNT_REGISTRY[mountId]!;
-    const gate = GATES[def.gate];
+    const guard = input.guards?.[mountId];
+    if (def.guarded && !guard) {
+      throw new Error(`mount "${mountId}" requires a guard — add one to ConstructInput.guards`);
+    }
     const options = declaration.options;
     const route = createRoute({
       id: `__mount_${mountId}`,
       getParentRoute: () => rootRoute,
-      ...(gate || options.beforeLoad
-        ? { beforeLoad: layoutBeforeLoad(gate, options.beforeLoad) }
+      ...(guard || options.beforeLoad
+        ? { beforeLoad: layoutBeforeLoad(guard, options.beforeLoad) }
         : {}),
       ...authoredOptions(options),
       component: options.component ?? Outlet,

packages/every-plugin/src/ui/manifest/index.ts

@@ -10,8 +10,6 @@ export {
   type ConstructInput,
   type ConstructPluginRef,
   constructTree,
-  type GateUser,
-  type HostContext,
   type ResolvedPlugin,
 } from "./construct";
 export * from "./contract";

packages/every-plugin/src/ui/manifest/mount-registry.ts

@@ -1,40 +1,40 @@
 /**
- * Mount registry v2 — gates only, shape-free (ADR 0008 §3).
+ * Mount registry v2 — shape-free (ADR 0008 §3).
  *
- * A mount is a gate + a host-owned pathless layout position. It carries no
- * product semantics (no "dashboard", no shell, no chrome) — plugins bring
- * their own layouts and route freely inside their subtree. A mount is
- * declared by a ROOT-level pathless layout file whose `_`-prefixed segment
- * names the mount (`_public.tsx` → `public`); the generator derives it and
- * validates it against this registry; gates are attached HOST-side at
- * construction, so a plugin cannot ship a route that escapes its mount's
- * gate (plugins never construct route objects).
+ * A mount is a host-owned pathless layout position. It carries no product
+ * semantics (no "dashboard", no shell, no chrome) — plugins bring their own
+ * layouts and route freely inside their subtree. A mount is declared by a
+ * ROOT-level pathless layout file whose `_`-prefixed segment names the mount
+ * (`_public.tsx` → `public`); the generator derives it and validates it
+ * against this registry; guards are ordinary beforeLoads attached HOST-side
+ * at construction from ConstructInput.guards, so a plugin cannot ship a
+ * route that escapes its mount's guard (plugins never construct route
+ * objects).
  *
- * `org`/`team` are declared vocabulary (parameterized membership gates) but
+ * `org`/`team` are declared vocabulary (parameterized membership) but
  * unimplemented — construction rejects them until they land.
  */
 
 export interface MountDef {
-  label: string;
-  gate: "none" | "session" | "admin" | "organization" | "team";
-  parameterized?: boolean;
+  /** The composing framework supplies this mount's guard via ConstructInput.guards. */
+  guarded: boolean;
   implemented: boolean;
 }
 
 export const MOUNT_REGISTRY = {
-  public: { label: "public", gate: "none", implemented: true },
-  authenticated: { label: "authenticated", gate: "session", implemented: true },
-  admin: { label: "admin", gate: "admin", implemented: true },
-  org: { label: "org", gate: "organization", parameterized: true, implemented: false },
-  team: { label: "team", gate: "team", parameterized: true, implemented: false },
-} satisfies Record<string, MountDef>;
+  public: { guarded: false, implemented: true },
+  authenticated: { guarded: true, implemented: true },
+  admin: { guarded: true, implemented: true },
+  org: { guarded: true, implemented: false },
+  team: { guarded: true, implemented: false },
+} as const satisfies Record<string, MountDef>;
 
 export type MountId = Extract<keyof typeof MOUNT_REGISTRY, string>;
 
 export const MOUNTS = Object.keys(MOUNT_REGISTRY) as MountId[];
 
 /** Bump when the registry shape changes — invalidates all compose digests. */
-export const MOUNT_REGISTRY_VERSION = 5;
+export const MOUNT_REGISTRY_VERSION = 6;
 
 /** Migration aliases: legacy `_`-segment names → canonical mounts. */
 export const MOUNT_ALIASES: Record<string, MountId> = {

packages/every-plugin/tests/unit/construct-precedence.test.ts

@@ -284,6 +284,7 @@ describe("constructTree core-over-plugin precedence (ADR 0010 decision #1)", ()
     const tree = await constructTree({
       name: "server",
       plugins: [core.ref, auth.ref],
+      guards: { authenticated: async () => undefined, admin: async () => undefined },
       resolve: async (ref) => {
         if (ref.key === "ui") return core.resolve(ref);
         return { key: "auth", manifest: authManifest, routeConfig: authConfig };

packages/everything-dev/package.json

@@ -378,6 +378,15 @@
       "import": "./dist/ui/manifest/index.mjs",
       "require": "./dist/ui/manifest/index.cjs"
     },
+    "./ui/compose": {
+      "development": {
+        "types": "./src/ui/compose.ts",
+        "import": "./src/ui/compose.ts"
+      },
+      "types": "./dist/ui/compose.d.mts",
+      "import": "./dist/ui/compose.mjs",
+      "require": "./dist/ui/compose.cjs"
+    },
     "./ui/manifest-generator": {
       "development": {
         "types": "./src/ui/manifest-generator.ts",

packages/everything-dev/src/services/scaffold/upgrade-audit/checks/compose-seam.ts

@@ -65,6 +65,7 @@ export type ConstructTreeFn = (input: {
     routeConfig: { routeConfigLoaders: Record<string, () => Promise<unknown>> };
   }>;
   rootOptions?: unknown;
+  guards?: Record<string, unknown>;
 }) => Promise<{ mountCounts: Record<string, number> }>;
 
 /** Pure — "unresolvable parentage" after a shadow log is the known cascade bug. */
@@ -125,6 +126,7 @@ export const runComposeProbe = async (
           { key: CORE_UI_KEY, mfName: CORE_UI_KEY },
           { key: AUTH_PLUGIN_KEY, mfName: AUTH_PLUGIN_KEY },
         ],
+        guards: { authenticated: async () => undefined, admin: async () => undefined },
         resolve: async (ref) => {
           const manifest = manifests.get(ref.key);
           if (!manifest) {