@bhooai/nexus-core 2.0.18 → 2.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-core",
-    "version": "2.0.18",
+    "version": "2.0.19",
     "publishConfig": {
         "access": "public"
     },

package/src/app/adminModule.ts

@@ -40,7 +40,7 @@ import type { Router } from '../http/Router.js';
 import type { Middleware, RequestContext } from '../http/context.js';
 import { AiClient } from '@bhooai/nexus-ai-client';
 import { discoverUserConfigPath, frameworkDefaultConfigPath, mergeConfig } from '../config/ConfigLoader.js';
-import { mongoEnabled, mongoUri } from '../config/dbAccess.js';
+import { mongoEnabled, mongoUri, cacheActive } from '../config/dbAccess.js';
 import { readRuntimeJson, writeRuntimeJson, mergeRuntimeJson } from '../config/runtimeJson.js';
 import { readEnvFile, writeEnvEntries, writeEnvKey, deleteEnvKey } from '../config/envFile.js';
 import {
@@ -173,17 +173,19 @@ export function registerAdminRoutes(router: Router, opts: AdminModuleOptions, lo
     const redisHost = hostOf(config.redis.url, 'localhost');
     const redisPort = portOf(config.redis.url, 6379);
     const aiPort = portOf(config.ai.serverUrl, 8000);
+    const useRedis = cacheActive(config) === 'redis';
 
     const [mongo, redis, ai] = await Promise.all([
       tcpReachable(mongoHost, mongoPort),
-      tcpReachable(redisHost, redisPort),
+      // No Redis server is required when fusion is the active cache backend.
+      useRedis ? tcpReachable(redisHost, redisPort) : Promise.resolve(true),
       tcpReachable('127.0.0.1', aiPort),
     ]);
 
     ctx.json({
       services: [
         { id: 'mongo', label: 'MongoDB', ok: mongo, detail: `${mongoHost}:${mongoPort}` },
-        { id: 'redis', label: 'Redis', ok: redis, detail: `${redisHost}:${redisPort}` },
+        { id: 'redis', label: 'Redis', ok: redis, detail: useRedis ? `${redisHost}:${redisPort}` : 'bypassed — fusion cache active' },
         { id: 'ai', label: 'AI server', ok: ai, detail: `127.0.0.1:${aiPort}` },
         { id: 'storage', label: 'Storage', ok: true, detail: 'local disks configured' },
       ],

package/src/app/authModule.ts

@@ -21,6 +21,8 @@
  */
 import type { NexusConfig } from '../config/types.js';
 import type { Router } from '../http/Router.js';
+import type { Middleware } from '../http/context.js';
+import { getNexusConfig } from '../config/current.js';
 import {
   AuthService,
   MemorySessionStore,
@@ -73,10 +75,51 @@ function jwtOptions(config: NexusConfig) {
   };
 }
 
-function authService(config: NexusConfig): AuthService {
+/**
+ * Build the framework AuthService for a config. Exported so app routes and
+ * subgraphs can verify the same session JWTs (issuer/audience/secret) without
+ * re-declaring identity values — e.g. the license routes.
+ */
+export function createAuthService(config: NexusConfig): AuthService {
   return new AuthService(jwtOptions(config), getSessions());
 }
 
+function authService(config: NexusConfig): AuthService {
+  return createAuthService(config);
+}
+
+let cachedAuth: { config: NexusConfig; service: AuthService } | null = null;
+
+/**
+ * Memoized AuthService for a config — safe to call per request. Rebuilt only
+ * when the config object identity changes.
+ */
+export function getAuthService(config: NexusConfig): AuthService {
+  if (cachedAuth?.config === config) return cachedAuth.service;
+  const service = createAuthService(config);
+  cachedAuth = { config, service };
+  return service;
+}
+
+/**
+ * Session-auth middleware that reads its identity from the request's config
+ * (`ctx.config`, falling back to the process config) instead of hardcoding a
+ * cookie name. Use before `requireAuth()`:
+ *
+ *   middleware: [sessionAuth(), requireAuth()]
+ */
+export function sessionAuth(options: { required?: boolean } = {}): Middleware {
+  return async (ctx, next) => {
+    const config = (ctx.config ?? getNexusConfig()) as NexusConfig | null;
+    if (!config) throw new Error('sessionAuth: no config available (ctx.config / setNexusConfig)');
+    const verify = authToken(getAuthService(config), {
+      required: options.required ?? false,
+      cookieName: config.auth.cookieName,
+    });
+    await verify(ctx, next);
+  };
+}
+
 /** Register /auth/* routes onto the given router. The user store is initialized
  *  by `createNexusApp()` (or lazily falls back to Mongo on first use). */
 export function registerAuthRoutes(router: Router, config: NexusConfig, onUserCreated?: () => void): AuthService {

package/src/app/createNexusApp.ts

@@ -15,7 +15,7 @@
 import { existsSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
 import { readFile } from 'node:fs/promises';
-import { loadConfigAuto, activeDatabase, mongoEnabled, mongoUri, fusionEnabled, type NexusConfig } from '../config/index.js';
+import { loadConfigAuto, activeDatabase, mongoEnabled, mongoUri, fusionEnabled, fusionRemote, setNexusConfig, type NexusConfig } from '../config/index.js';
 import { Container } from '../di/Container.js';
 import { Router } from '../http/Router.js';
 import { NexusServer } from '../http/Server.js';
@@ -29,6 +29,7 @@ import { ConfigError, NotFoundError, toNexusError } from '../errors.js';
 import { initUserModel } from './userModel.js';
 import { initUserStore, MongoUserStore, FusionUserStore } from './userStore.js';
 import { openAppFusion, closeAppFusion } from './fusionEngine.js';
+import { registerFusionDevRoutes } from './fusionDevApi.js';
 import { eventBus, type EventBus, type Listener } from './events.js';
 import { configureQueue, InMemoryQueueAdapter, type JobQueueAdapter } from './Job.js';
 import { configureMailDriver, configureMailRenderer, logMailDriver } from './Mailable.js';
@@ -51,8 +52,19 @@ export interface CreateNexusAppOptions {
   tech?: 'react' | 'future';
   /** Path to the backend src/ folder. Defaults to `<cwd>/src`. */
   srcRoot?: string;
-  /** Project root (where .nexus-down and storage/ live). Defaults to srcRoot/.. */
+  /** Project root — anchors DB data, cache, logs and certs (`storage/fusion`,
+   *  `storage/logs`, `certs/`, .nexus-down). Defaults to srcRoot/.. */
   projectRoot?: string;
+  /**
+   * Root for file storage (uploads + private). Resolves to
+   * `<storageRoot>/storage/{uploads,private}` and is served at `/uploads`.
+   *
+   * Split from `projectRoot` so a monorepo can keep durable DB data at the
+   * workspace root while file uploads live next to the backend
+   * (e.g. projectRoot = repo root, storageRoot = apps/backend).
+   * Defaults to `projectRoot`.
+   */
+  storageRoot?: string;
   /** Override the auto-discovered config (for tests). */
   config?: NexusConfig;
   /** Additional global middleware applied after built-ins. */
@@ -102,6 +114,9 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   const name = opts.name ?? 'backend';
   const srcRoot = resolve(opts.srcRoot ?? resolve(process.cwd(), 'src'));
   const projectRoot = resolve(opts.projectRoot ?? dirname(srcRoot));
+  // File storage (uploads/private) can be anchored separately from projectRoot
+  // so DB data stays at the workspace root while files live with the backend.
+  const storageRoot = resolve(opts.storageRoot ?? projectRoot);
   let config = opts.config ?? (await loadConfigAuto({ root: projectRoot }));
 
   // License check at project start — verify the token (signature via fetched
@@ -137,6 +152,10 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     config = Object.freeze({ ...config, server: { ...config.server, port: finalPort } }) as NexusConfig;
   }
 
+  // Publish the resolved config process-wide so subgraphs/services without a
+  // request context can read identity/namespace values (see getNexusConfig).
+  setNexusConfig(config);
+
   const container = new Container();
   const router = new Router();
 
@@ -171,6 +190,16 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     }
     const fusionDb = await openAppFusion(projectRoot, config);
     initUserStore(new FusionUserStore(fusionDb));
+    // Dev-only: expose this same engine over HTTP so `nexus dev`'s Fusion View
+    // and `nexus db:view` read/write the SAME state the backend serves from —
+    // no second engine, no stale reads, no refresh needed.
+    //
+    // Skipped in remote mode: the standalone Fusion server already speaks HTTP,
+    // so tooling talks to it directly (the backend owns no engine to expose).
+    if (config.env === 'development' && !fusionRemote(config)) {
+      registerFusionDevRoutes(router);
+      console.log(`[${name}] Fusion dev API mounted (dev only)`);
+    }
   } else {
     if (mongoEnabled(config)) initUserModel();
     initUserStore(new MongoUserStore());
@@ -179,7 +208,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // ------------------------------------------------------------------
   // Storage facade + queue + mail — always configured, even if minimal
   // ------------------------------------------------------------------
-  configureStorageFromEnv(projectRoot, config.auth?.jwt?.secret ?? 'nexus-insecure');
+  configureStorageFromEnv(storageRoot, config.auth?.jwt?.secret ?? 'nexus-insecure');
   configureQueue(opts.queueAdapter ?? new InMemoryQueueAdapter());
   configureMailDriver(logMailDriver);
   configureMailRenderer(async (templateName, data) => renderMailTemplate(projectRoot, templateName, data));
@@ -386,7 +415,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
           gateway,
           introspection: config.graphql?.introspection ?? true,
           requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true,
-          context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), ...opts.graphqlContext }),
+          context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), config: ctx.config ?? config, ...opts.graphqlContext }),
         });
         if (explorerEnabled) {
           const explorerHtml = getExplorerHtml({
@@ -433,7 +462,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
         if (helloEnabled) {
           // hello is available even in fallback — route through its gateway
           const gw = createGateway({ subgraph: helloSubgraph });
-          const h = graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true, context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), ...opts.graphqlContext }) });
+          const h = graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true, context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), config: ctx.config ?? config, ...opts.graphqlContext }) });
           return h(ctx);
         }
         ctx.json({ errors: [{ message: 'No GraphQL subgraph found. Add one with: npx nexus make:subgraph <name>  (then restart)' }] }, 404);
@@ -443,7 +472,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
       try {
         if (helloEnabled) {
           const gw = createGateway({ subgraph: helloSubgraph });
-          router.add('POST', graphqlPath, graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true, context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), ...opts.graphqlContext }) }));
+          router.add('POST', graphqlPath, graphqlHttpHandler({ gateway: gw, introspection: config.graphql?.introspection ?? true, requireMutationCsrf: config.graphql?.requireMutationCsrf ?? true, context: (ctx) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), config: ctx.config ?? config, ...opts.graphqlContext }) }));
         } else {
           router.add('POST', graphqlPath, async (ctx) => ctx.json({ errors: [{ message: 'No GraphQL subgraph found. Add one with: npx nexus make:subgraph <name>' }] }, 404));
         }
@@ -510,6 +539,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // ------------------------------------------------------------------
   const server = new NexusServer({
     router,
+    config,
     bodyLimit: config.server.bodyLimit,
     trustProxy: config.server.trustProxy,
     ...(config.server.https && config.server.certFile && config.server.keyFile
@@ -717,9 +747,9 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     }
   }
 
-  // Public uploads: serve GET /uploads/* from storage/uploads (file-storage example).
+  // Public uploads: serve GET /uploads/* from <storageRoot>/storage/uploads.
   // This was missing — 404 `No route for GET /uploads/media/...`.
-  server.use(serveStatic(join(projectRoot, 'storage', 'uploads'), { prefix: '/uploads' }));
+  server.use(serveStatic(join(storageRoot, 'storage', 'uploads'), { prefix: '/uploads' }));
 
   // Signed private files: GET /files/<encodedPath>?expires=&sig=
   // Handles LocalDisk.signedUrl() URLs (HMAC, 5min TTL). Streams from whichever local disk holds the file.

package/src/app/databaseAdminModule.ts

@@ -1,7 +1,7 @@
 import type { Router } from '../index.js';
 import type { ActiveDatabase } from '../config/types.js';
 import { getAppFusion } from './fusionEngine.js';
-import type { FusionDatabase } from '@bhooai/nexus-fusion';
+import type { FusionLike } from '@bhooai/nexus-fusion';
 
 /**
  * Admin routes for database / collection administration.
@@ -213,14 +213,14 @@ function registerMongoDatabaseAdminRoutes(router: Router, lazy: LazyDb): void {
 
 function registerFusionDatabaseAdminRoutes(router: Router): void {
   // Branches stand in for databases; the engine's fixed db is 'main'.
-  const view = (branch: string): FusionDatabase => getAppFusion().branchView(branch);
+  const view = (branch: string): FusionLike => getAppFusion().branchView(branch);
 
   router.get('/admin/databases', async (ctx) => {
     try {
       const fusion = getAppFusion();
       const databases = [];
-      for (const branch of fusion.listBranches()) {
-        const bcols = view(branch).listCollections().filter((c) => c !== BOOTSTRAP_COLLECTION);
+      for (const branch of await fusion.listBranches()) {
+        const bcols = (await view(branch).listCollections()).filter((c) => c !== BOOTSTRAP_COLLECTION);
         const collections = [];
         for (const c of bcols) {
           let count = 0;
@@ -242,7 +242,7 @@ function registerFusionDatabaseAdminRoutes(router: Router): void {
     const name = assertDbName((ctx.body as { name?: unknown } | undefined)?.name, ctx);
     if (!name) return;
     try {
-      getAppFusion().createBranch(name);
+      await getAppFusion().createBranch(name);
       ctx.json({ ok: true, name });
     } catch (err) {
       ctx.json({ error: (err as Error).message }, 500);
@@ -253,7 +253,7 @@ function registerFusionDatabaseAdminRoutes(router: Router): void {
     const name = assertDbName(ctx.params.db, ctx);
     if (!name) return;
     try {
-      getAppFusion().dropBranch(name);
+      await getAppFusion().dropBranch(name);
       ctx.json({ ok: true, dropped: name });
     } catch (err) {
       ctx.json({ error: (err as Error).message }, 500);

package/src/app/fusionDevApi.ts

@@ -0,0 +1,210 @@
+/**
+ * Fusion dev API — exposes the backend's **own** in-process Fusion engine over
+ * HTTP so the CLI tools (`nexus dev` Fusion View, `nexus db:view`) read and
+ * write the SAME engine the app serves from.
+ *
+ * Before this existed, the standalone `fusion` service opened a *second*
+ * engine on the same `storage/fusion/fusion.wal`. Edits made in the browser
+ * landed in engine B, so the running backend (engine A) kept serving stale
+ * data until it restarted and replayed the WAL.
+ *
+ * Mounted only in development (`config.env === 'development'`) and only when
+ * `db.active === 'fusion'`. Routes mirror the standalone server's surface
+ * (see `nexus-cli/src/fusion/server.ts`) so one browser client works against
+ * either backend:
+ *
+ *   GET    <prefix>/health
+ *   GET    <prefix>/tree
+ *   GET    <prefix>/docs?collection=&branch=&where=&orderBy=&limit=&skip=
+ *   POST   <prefix>/docs            { branch, collection, id?, data }
+ *   PATCH  <prefix>/docs/:id?collection=&branch=      (body = patch)
+ *   DELETE <prefix>/docs/:id?collection=&branch=
+ *   POST   <prefix>/branches        { branch }
+ *   DELETE <prefix>/branches/:name
+ */
+import type { Router } from '../http/Router.js';
+import type { RequestContext } from '../http/context.js';
+import { getAppFusion } from './fusionEngine.js';
+
+/** Reserved mount path — double underscore marks it framework-internal. */
+export const FUSION_DEV_PATH = '/__nexus/fusion';
+
+/** Map a Fusion engine error (`.code`) to an HTTP status. */
+function httpStatus(err: unknown): number {
+  const code = (err as { code?: string })?.code;
+  switch (code) {
+    case 'NOT_FOUND':
+    case 'PATH_NOT_FOUND':
+      return 404;
+    case 'VERSION_CONFLICT':
+      return 409;
+    case 'INVALID_NAME':
+    case 'INVALID_ID':
+    case 'QUERY_ERROR':
+      return 400;
+    default:
+      return 500;
+  }
+}
+
+function fail(ctx: RequestContext, err: unknown): void {
+  ctx.json({ error: err instanceof Error ? err.message : String(err) }, httpStatus(err));
+}
+
+/**
+ * Register the Fusion dev routes on `router` under `prefix`. Safe to call for
+ * non-fusion backends? No — the caller must gate on db.active === 'fusion'
+ * (getAppFusion throws otherwise), which `createNexusApp` does.
+ */
+export function registerFusionDevRoutes(router: Router, prefix: string = FUSION_DEV_PATH): void {
+  const at = (path: string): string => `${prefix.replace(/\/+$/, '')}${path}`;
+
+  router.get(at('/health'), (ctx) => {
+    ctx.json({ ok: true, db: getAppFusion().db });
+  });
+
+  // Tree — branches → collections with counts (same shape as the standalone server).
+  router.get(at('/tree'), async (ctx) => {
+    try {
+      const db = getAppFusion();
+      const tree: {
+        db: string;
+        branches: Array<{ name: string; collections: Array<{ name: string; count: number }> }>;
+      } = { db: db.db, branches: [] };
+      for (const name of await db.listBranches()) {
+        const view = db.branchView(name);
+        const collections: Array<{ name: string; count: number }> = [];
+        for (const coll of await view.listCollections()) {
+          collections.push({ name: coll, count: await view.collection(coll).count() });
+        }
+        tree.branches.push({ name, collections });
+      }
+      ctx.json({ tree });
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+
+  // Docs list.
+  router.get(at('/docs'), async (ctx) => {
+    try {
+      const q = ctx.query as Record<string, string>;
+      const collection = q.collection;
+      if (!collection) return ctx.json({ error: 'collection query param required' }, 400);
+      const view = getAppFusion().branchView(q.branch || 'prod');
+      let query = view.collection(collection).query();
+      if (q.where) {
+        const parsed = JSON.parse(q.where) as
+          | { field: string; op: string; value: unknown }
+          | Array<{ field: string; op: string; value: unknown }>;
+        const conds = Array.isArray(parsed) ? parsed : [parsed];
+        for (const c of conds) query = query.where(c.field, c.op as never, c.value);
+      }
+      if (q.orderBy) {
+        const [field, dir] = q.orderBy.split(':');
+        if (field) query = query.orderByField(field, dir === 'desc' ? 'desc' : 'asc');
+      }
+      if (q.skip) query = query.offset(Number(q.skip) || 0);
+      if (q.limit) query = query.limit(Number(q.limit) || 50);
+      const snap = await query.get();
+      ctx.json({
+        docs: snap.docs.map((d) => ({
+          id: d.id,
+          version: d.__version,
+          updatedAt: d.__updatedAt,
+          data: d.data,
+        })),
+        size: snap.size,
+      });
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+
+  // Create doc.
+  router.post(at('/docs'), async (ctx) => {
+    try {
+      const body = (ctx.body ?? {}) as { branch?: string; collection?: string; id?: string; data?: Record<string, unknown> };
+      const collection = body.collection;
+      const data = body.data;
+      if (!collection || typeof data !== 'object' || data === null) {
+        return ctx.json({ error: 'collection and data required' }, 400);
+      }
+      const view = getAppFusion().branchView(body.branch || 'prod');
+      const doc = body.id
+        ? await view.collection(collection).doc(body.id).set(data)
+        : await view.collection(collection).add(data);
+      const id = body.id ?? (doc as { id: string }).id;
+      const saved = await view.collection(collection).doc(id).get();
+      ctx.json(
+        {
+          doc: saved
+            ? { id: saved.id, version: saved.__version, updatedAt: saved.__updatedAt, data: saved.data }
+            : null,
+        },
+        201,
+      );
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+
+  // Patch doc.
+  router.patch(at('/docs/:id'), async (ctx) => {
+    try {
+      const q = ctx.query as Record<string, string>;
+      const collection = q.collection;
+      if (!collection) return ctx.json({ error: 'collection query param required' }, 400);
+      const patch = (ctx.body ?? {}) as Record<string, unknown>;
+      const updated = await getAppFusion()
+        .branchView(q.branch || 'prod')
+        .collection(collection)
+        .doc(ctx.params.id ?? '')
+        .update(patch);
+      ctx.json({
+        doc: { id: updated.id, version: updated.__version, updatedAt: updated.__updatedAt, data: updated.data },
+      });
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+
+  // Delete doc.
+  router.delete(at('/docs/:id'), async (ctx) => {
+    try {
+      const q = ctx.query as Record<string, string>;
+      const collection = q.collection;
+      if (!collection) return ctx.json({ error: 'collection query param required' }, 400);
+      await getAppFusion()
+        .branchView(q.branch || 'prod')
+        .collection(collection)
+        .doc(ctx.params.id ?? '')
+        .delete();
+      ctx.json({ ok: true });
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+
+  // Create branch.
+  router.post(at('/branches'), async (ctx) => {
+    try {
+      const body = (ctx.body ?? {}) as { branch?: string };
+      if (!body.branch) return ctx.json({ error: 'branch required' }, 400);
+      await getAppFusion().createBranch(body.branch);
+      ctx.json({ ok: true, branch: body.branch }, 201);
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+
+  // Drop branch.
+  router.delete(at('/branches/:name'), async (ctx) => {
+    try {
+      await getAppFusion().dropBranch(ctx.params.name ?? '');
+      ctx.json({ ok: true });
+    } catch (err) {
+      fail(ctx, err);
+    }
+  });
+}

package/src/app/fusionEngine.ts

@@ -1,20 +1,31 @@
 import { mkdir } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import type { FusionDatabase } from '@bhooai/nexus-fusion';
+import type { FusionLike } from '@bhooai/nexus-fusion';
 import type { NexusConfig } from '../config/types.js';
-import { fusionDir } from '../config/dbAccess.js';
+import { fusionDir, fusionRemote, fusionUrl } from '../config/dbAccess.js';
 
 /**
- * App Fusion engine lifecycle — one engine per backend process, opened at
- * boot when `db.fusion.enabled` and closed on shutdown.
+ * App Fusion engine lifecycle — one per backend process.
+ *
+ * Two modes, selected by config:
+ *
+ *  - **Embedded** (default): opens the native `@bhooai/nexus-fusion` engine at
+ *    boot when `db.fusion.enabled` and closes it on shutdown. The backend owns
+ *    `storage/fusion/fusion.wal`.
+ *
+ *  - **Remote**: when `db.fusion.remote` is true (or `db.fusion.url` is set) the
+ *    backend opens **no** engine. All reads/writes go over HTTP to the
+ *    standalone `fusion` service started by `nexus dev`, which is the sole
+ *    owner of the WAL. This lets several apps share one Fusion database and
+ *    keeps the backend process free of the Rust engine.
  *
  * `@bhooai/nexus-fusion` is dynamically imported so mongo-only backends never
  * need the package (or its Rust core) installed.
  */
 
-let engine: FusionDatabase | null = null;
+let engine: FusionLike | null = null;
 
-export async function openAppFusion(projectRoot: string, config: NexusConfig): Promise<FusionDatabase> {
+export async function openAppFusion(projectRoot: string, config: NexusConfig): Promise<FusionLike> {
   if (engine) return engine;
   let mod: typeof import('@bhooai/nexus-fusion');
   try {
@@ -25,6 +36,29 @@ export async function openAppFusion(projectRoot: string, config: NexusConfig): P
         'add it as a dependency (file:../path/to/packages/nexus-fusion) and install.',
     );
   }
+
+  if (fusionRemote(config)) {
+    const url = fusionUrl(config);
+    if (!url) {
+      throw new Error(
+        "[db] db.fusion.remote is true but db.fusion.url is empty — set it to the standalone " +
+          'Fusion server (e.g. http://127.0.0.1:5000).',
+      );
+    }
+    engine = mod.fusionHttp({ url });
+    // Confirm the standalone server answers before the backend serves traffic.
+    try {
+      await (engine as { listBranches(): Promise<string[]> }).listBranches();
+      console.log(`[db] fusion remote client → ${url}`);
+    } catch (err) {
+      console.warn(
+        `[db] fusion server at ${url} is not reachable yet (${(err as Error).message}); ` +
+          'requests will retry once it is up.',
+      );
+    }
+    return engine;
+  }
+
   const fz = config.db.fusion;
   const dir = fz.persist ? resolve(projectRoot, fusionDir(config)) : undefined;
   if (dir) await mkdir(dir, { recursive: true });
@@ -38,7 +72,7 @@ export async function openAppFusion(projectRoot: string, config: NexusConfig): P
   return engine;
 }
 
-export function getAppFusion(): FusionDatabase {
+export function getAppFusion(): FusionLike {
   if (!engine) throw new Error('[db] Fusion engine is not open — enable db.fusion first.');
   return engine;
 }
@@ -46,7 +80,7 @@ export function getAppFusion(): FusionDatabase {
 export async function closeAppFusion(): Promise<void> {
   if (!engine) return;
   try {
-    engine.close();
+    await engine.close();
   } finally {
     engine = null;
   }

package/src/app/index.ts

@@ -18,3 +18,4 @@ export * from './authModule.js';
 export * from './userModel.js';
 export * from './userStore.js';
 export * from './fusionEngine.js';
+export * from './fusionDevApi.js';

package/src/app/preflightModule.ts

@@ -1,6 +1,6 @@
 import { createConnection } from 'node:net';
 import type { Router, NexusConfig } from '../index.js';
-import { mongoEnabled, mongoUri } from '../config/dbAccess.js';
+import { mongoEnabled, mongoUri, redisCacheEnabled } from '../config/dbAccess.js';
 
 /**
  * Preflight diagnostics — native Node connectivity/latency probes.
@@ -235,7 +235,9 @@ export function registerPreflightRoutes(router: Router, config: NexusConfig, opt
     }
 
     const redisUrl = config.redis?.url ?? '';
-    if (redisUrl) {
+    // Probed only when redis is the active cache backend — fusion-active
+    // backends don't need a Redis server at all.
+    if (redisCacheEnabled(config) && redisUrl) {
       const redis = endpointFromUrl(redisUrl, 6379);
       targets.push({ name: 'Redis', kind: 'tcp', host: redis.host, port: redis.port, timeout: 2000 });
     }

package/src/app/userStore.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import type { FusionDatabase } from '@bhooai/nexus-fusion';
+import type { FusionLike } from '@bhooai/nexus-fusion';
 import { ObjectId } from '@bhooai/nexus-data';
 import { ConflictError } from '../errors.js';
 import { initUserModel, getUserModel, findUserForLogin, type UserInstance } from './userModel.js';
@@ -172,16 +172,16 @@ async function getDocOrNull<T>(ref: { get(): Promise<{ id: string; data: T } | n
 }
 
 /** Query paths throw on missing collections too — treat as empty. */
-function hasCollection(db: FusionDatabase, name: string): boolean {
+async function hasCollection(db: FusionLike, name: string): Promise<boolean> {
   try {
-    return db.listCollections().includes(name);
+    return (await db.listCollections()).includes(name);
   } catch {
     return false;
   }
 }
 
 export class FusionUserStore implements UserStore {
-  constructor(private db: FusionDatabase) {}
+  constructor(private db: FusionLike) {}
 
   private toStored(data: FusionUserData): StoredUser {
     return { _id: data.id, ...data };
@@ -197,7 +197,7 @@ export class FusionUserStore implements UserStore {
   }
 
   async findById(id: string): Promise<StoredUser | null> {
-    if (!hasCollection(this.db, USERS)) return null;
+    if (!(await hasCollection(this.db, USERS))) return null;
     const snap = await this.db.collection<FusionUserData>(USERS).where('id', '==', id).limit(1).get();
     const hit = snap.docs[0];
     return hit ? this.toStored(hit.data) : null;
@@ -255,20 +255,20 @@ export class FusionUserStore implements UserStore {
   }
 
   async count(): Promise<number> {
-    if (!hasCollection(this.db, USERS)) return 0;
+    if (!(await hasCollection(this.db, USERS))) return 0;
     const snap = await this.db.collection(USERS).get();
     return snap.size;
   }
 
   async countAdmins(): Promise<number> {
     // No array-contains op in the query compiler — filter the (small) users table.
-    if (!hasCollection(this.db, USERS)) return 0;
+    if (!(await hasCollection(this.db, USERS))) return 0;
     const snap = await this.db.collection<FusionUserData>(USERS).get();
     return snap.docs.filter((d) => (d.data.roles ?? []).includes('admin')).length;
   }
 
   async list(limit: number): Promise<StoredUser[]> {
-    if (!hasCollection(this.db, USERS)) return [];
+    if (!(await hasCollection(this.db, USERS))) return [];
     const snap = await this.db
       .collection<FusionUserData>(USERS)
       .orderByField('createdAt', 'desc')

package/src/config/ConfigLoader.ts

@@ -47,6 +47,23 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
     merged = deepMerge(merged, defaultConfig);
   }
 
+  // 1c. project identity — resolve `app.name` from every higher layer, then
+  //     derive auth identity, redis prefix and mail `from` from it. This layer
+  //     sits above the framework default but below the user config, so an
+  //     explicit value anywhere in nexus.config.ts / runtime.json / env still
+  //     wins while a project only has to declare its name once.
+  const runtimePath = opts.runtimePath ?? resolve(root, 'nexus.runtime.json');
+  const runtime = readRuntimeObject(runtimePath);
+  const envLayer = configFromEnv(env);
+  const appName = resolveAppName({
+    userConfig: opts.userConfig,
+    runtime,
+    env: envLayer,
+    cli: opts.cli,
+    root,
+  });
+  merged = deepMerge(merged, deriveAppIdentity(appName));
+
   // 2. user config (nexus.config.ts / nexus.config.js)
   let userConfig = opts.userConfig;
   if (!userConfig && opts.userConfigPath) {
@@ -55,18 +72,10 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
   if (userConfig) merged = deepMerge(merged, userConfig);
 
   // 3. runtime.json (admin write-back, gitignored)
-  const runtimePath = opts.runtimePath ?? resolve(root, 'nexus.runtime.json');
-  if (existsSync(runtimePath)) {
-    try {
-      const runtime = JSON.parse(readFileSync(runtimePath, 'utf8')) as DeepPartial<NexusConfig>;
-      merged = deepMerge(merged, runtime);
-    } catch {
-      // A corrupt runtime file must not crash boot; ignore it.
-    }
-  }
+  if (runtime) merged = deepMerge(merged, runtime);
 
   // 4. env
-  merged = deepMerge(merged, configFromEnv(env));
+  merged = deepMerge(merged, envLayer);
 
   // 5. cli flags (highest)
   if (opts.cli) merged = deepMerge(merged, opts.cli);
@@ -76,6 +85,65 @@ export async function loadConfig(opts: LoadOptions = {}): Promise<NexusConfig> {
   return Object.freeze(parsed) as NexusConfig;
 }
 
+/** Read nexus.runtime.json (DeepPartial) or an empty object when absent/corrupt. */
+function readRuntimeObject(runtimePath: string): DeepPartial<NexusConfig> {
+  if (!existsSync(runtimePath)) return {};
+  try {
+    return JSON.parse(readFileSync(runtimePath, 'utf8')) as DeepPartial<NexusConfig>;
+  } catch {
+    // A corrupt runtime file must not crash boot; ignore it.
+    return {};
+  }
+}
+
+/**
+ * Resolve the project slug used to derive identity/namespaces: an explicit
+ * `app.name` from the highest-precedence layer wins, else package.json `name`
+ * (scope stripped), else the project folder name.
+ */
+function resolveAppName(layers: {
+  userConfig?: UserNexusConfig;
+  runtime?: DeepPartial<NexusConfig>;
+  env?: DeepPartial<NexusConfig>;
+  cli?: DeepPartial<NexusConfig>;
+  root: string;
+}): string {
+  const explicit =
+    layers.cli?.app?.name ??
+    layers.env?.app?.name ??
+    layers.runtime?.app?.name ??
+    layers.userConfig?.app?.name;
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim();
+
+  try {
+    const pkg = JSON.parse(readFileSync(join(layers.root, 'package.json'), 'utf8')) as { name?: string };
+    if (pkg.name) return pkg.name.replace(/^@[^/]+\//, '').trim();
+  } catch {
+    // no package.json
+  }
+  return layers.root.split(/[\\/]/).filter(Boolean).pop() ?? 'nexus';
+}
+
+/**
+ * Derive the per-project identity fields from `app.name`. Values are only
+ * applied as a base layer — an explicit value in a higher config layer wins
+ * (including `NEXUS_DB_URI`, which maps to `db.mongodb.uri` via the legacy
+ * flat shape).
+ */
+function deriveAppIdentity(appName: string): DeepPartial<NexusConfig> {
+  return {
+    app: { name: appName },
+    auth: {
+      jwt: { issuer: appName, audience: `${appName}-client` },
+      cookieName: `${appName}_sid`,
+      refreshCookieName: `${appName}_rid`,
+    },
+    redis: { keyPrefix: `${appName}:` },
+    db: { mongodb: { uri: `mongodb://localhost:27017/${appName}` } },
+    email: { from: `no-reply@${appName}.local` },
+  };
+}
+
 async function importUserConfig(absPath: string): Promise<UserNexusConfig> {
   const url = pathToFileURL(absPath).href;
   const mod = (await import(url)) as Record<string, unknown>;
@@ -155,7 +223,13 @@ export async function loadConfigAuto(
   });
 }
 
-/** Read-only accessor for tests / bootstrap that don't need file loading. */
+/**
+ * Read-only accessor for tests / bootstrap that don't need file loading.
+ * When any source declares `app.name`, the derived identity fields are applied
+ * as a base layer (an explicit value in a later source still wins).
+ */
 export function mergeConfig(...sources: DeepPartial<NexusConfig>[]): NexusConfig {
-  return Object.freeze(nexusConfigSchema.parse(deepMerge(defaults, ...sources))) as NexusConfig;
+  const explicitName = [...sources].reverse().find((s) => s?.app?.name)?.app?.name;
+  const base = explicitName ? deepMerge(defaults, deriveAppIdentity(explicitName)) : defaults;
+  return Object.freeze(nexusConfigSchema.parse(deepMerge(base, ...sources))) as NexusConfig;
 }

package/src/config/current.ts

@@ -0,0 +1,28 @@
+/**
+ * Process-wide accessor for the loaded config.
+ *
+ * `createNexusApp()` registers the merged config here at boot so code paths
+ * that are not handed a `ctx` (subgraphs, services, listeners, jobs) can read
+ * the same identity/namespace values instead of hardcoding them.
+ *
+ * This is a convenience fallback, not a replacement for DI — prefer the
+ * `ctx.config` / resolver-context value when a request context is available.
+ */
+import type { NexusConfig } from './types.js';
+
+let current: NexusConfig | null = null;
+
+/** Register the config for this process (called by createNexusApp at boot). */
+export function setNexusConfig(config: NexusConfig): void {
+  current = config;
+}
+
+/** The config registered for this process, or null before boot. */
+export function getNexusConfig(): NexusConfig | null {
+  return current;
+}
+
+/** Reset the process config (tests / hot reload). */
+export function resetNexusConfig(): void {
+  current = null;
+}

package/src/config/dbAccess.ts

@@ -24,3 +24,24 @@ export function fusionEnabled(config: NexusConfig): boolean {
 export function fusionDir(config: NexusConfig): string {
   return config.db.fusion.dir;
 }
+
+/** True when the backend delegates to a standalone Fusion server over HTTP
+ *  (no in-process engine). Triggered by `db.fusion.remote` or a set `url`. */
+export function fusionRemote(config: NexusConfig): boolean {
+  return config.db.fusion.remote === true || !!config.db.fusion.url;
+}
+
+/** Standalone Fusion server base URL (empty when embedded). */
+export function fusionUrl(config: NexusConfig): string {
+  return config.db.fusion.url ?? '';
+}
+
+/** Which backend serves cache duties — 'fusion' (default) or 'redis'. */
+export function cacheActive(config: NexusConfig): 'fusion' | 'redis' {
+  return config.cache?.active ?? 'fusion';
+}
+
+/** True when the app uses an external Redis server for cache. */
+export function redisCacheEnabled(config: NexusConfig): boolean {
+  return cacheActive(config) === 'redis';
+}

package/src/config/defaults.ts

@@ -6,6 +6,11 @@ import type { NexusConfig } from './types.js';
  */
 export const defaults: NexusConfig = {
   env: 'development',
+  app: {
+    // Overridden by ConfigLoader with the project slug (package.json name or
+    // folder name) when not set explicitly in nexus.config.ts.
+    name: 'nexus',
+  },
   server: {
     port: 4000,
     host: 'localhost',
@@ -30,6 +35,8 @@ export const defaults: NexusConfig = {
     },
     fusion: {
       enabled: true,
+      remote: false,
+      url: '',
       dir: 'storage/fusion',
       persist: true,
       cacheCapacity: 10_000,
@@ -87,11 +94,10 @@ export const defaults: NexusConfig = {
   },
   ads: {
     enabled: false,
-    developerToken: '',
+    publisherId: '',
     clientId: '',
     clientSecret: '',
     refreshToken: '',
-    customerId: '',
   },
   webrtc: {
     rtcMinPort: 40000,
@@ -131,7 +137,7 @@ export const defaults: NexusConfig = {
     level: 'info',
     format: 'pretty',
     console: true,
-    dir: 'logs',
+    dir: 'storage/logs',
     maxFileSize: 10 * 1024 * 1024, // 10 MiB
     maxFiles: 7,
   },
@@ -149,14 +155,8 @@ export const defaults: NexusConfig = {
     host: 'localhost',
     enabled: true,
   },
-  fusion: {
-    dir: 'storage/fusion',
-    persist: true,
-    cacheCapacity: 10_000,
-    cacheTtlMs: 5_000,
-    walCompactThreshold: 1_000,
-  },
   cache: {
+    active: 'fusion',
     dir: 'storage/fusion/cache',
     persist: true,
     cacheCapacity: 10_000,

package/src/config/env.ts

@@ -50,6 +50,26 @@ function coerce(value: string): string | number | boolean {
   return v;
 }
 
+/**
+ * Runtime-only `NEXUS_*` variables that are NOT config keys.
+ *
+ * These are process controls injected by the CLI / supervisor (`nexus dev` sets
+ * NEXUS_PORT and NEXUS_PORT_STEP on every child) or read directly by the
+ * framework at boot. Mapping them into the config tree corrupts it — e.g.
+ * NEXUS_PORT creates `{ port: 4000 }` and NEXUS_PORT_STEP then tries to write
+ * `port.step` onto that number, throwing `Cannot create property 'step' on
+ * number` and killing backend boot whenever ports step up.
+ */
+const RUNTIME_ENV_VARS = new Set([
+  'NEXUS_PORT',          // per-service resolved port (read by createNexusApp)
+  'NEXUS_PORT_STEP',     // coordinated step-up delta (read by the CLI)
+  'NEXUS_HOST',          // bind host injected by the supervisor
+  'NEXUS_PROJECT_ROOT',  // license/config resolution root injected by the CLI
+  'NEXUS_TUI_NO_MOUSE',  // dev panel control
+  'NEXUS_TUI_DEBUG',     // dev panel control
+  'NEXUS_AI_FIX',        // `nexus dev --ai-fix` toggle
+]);
+
 /**
  * Two `_`-separated env segments that form ONE camelCase config field.
  * Generic splitting would turn `KEY_ID` into `key.id` (a nested object) —
@@ -69,6 +89,8 @@ const PAIR_FIELDS: Record<string, string> = {
   'webhook_secret': 'webhookSecret',
   'customer_id': 'customerId',
   'developer_token': 'developerToken',
+  'publisher_id': 'publisherId',
+  'account_id': 'accountId',
   'refresh_token': 'refreshToken',
   'access_ttl': 'accessTtl',
   'refresh_ttl': 'refreshTtl',
@@ -91,6 +113,7 @@ export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial
   const out: Record<string, unknown> = {};
   for (const [rawKey, rawValue] of Object.entries(env)) {
     if (!rawKey.startsWith('NEXUS_') || rawValue === undefined) continue;
+    if (RUNTIME_ENV_VARS.has(rawKey)) continue;
     const path = rawKey.slice('NEXUS_'.length).toLowerCase().split('_');
     const last = path.length - 1;
     if (last >= 1) {
@@ -100,15 +123,37 @@ export function configFromEnv(env: NodeJS.ProcessEnv = process.env): DeepPartial
       }
     }
     let node: Record<string, unknown> = out;
+    let conflict = false;
     for (let i = 0; i < path.length; i++) {
       const segment = path[i]!;
       if (i === path.length - 1) {
         node[segment] = coerce(rawValue);
       } else {
-        node[segment] = (node[segment] as Record<string, unknown>) ?? {};
-        node = node[segment] as Record<string, unknown>;
+        const existing = node[segment];
+        // A scalar here means two env vars disagree about the shape (e.g.
+        // NEXUS_SERVER_PORT=4000 plus NEXUS_SERVER_PORT_X). Overwriting would
+        // either crash (writing a property onto a primitive) or silently drop
+        // config, so skip the offending var and keep the first value.
+        if (existing !== undefined && (typeof existing !== 'object' || existing === null)) {
+          conflict = true;
+          break;
+        }
+        const child = existing ?? {};
+        node[segment] = child;
+        node = child as Record<string, unknown>;
       }
     }
+    if (conflict && !isKnownRuntimeVar(rawKey)) {
+      // Real config vars would silently vanish — make that visible.
+      console.warn(
+        `[config] ignoring ${rawKey}: its path collides with a scalar already set by another NEXUS_* var`,
+      );
+    }
   }
   return out as DeepPartial<NexusConfig>;
+}
+
+/** True for vars the framework consumes at runtime rather than as config. */
+function isKnownRuntimeVar(key: string): boolean {
+  return RUNTIME_ENV_VARS.has(key);
 }

package/src/config/index.ts

@@ -4,4 +4,5 @@ export * from './merge.js';
 export * from './env.js';
 export * from './schema.js';
 export * from './dbAccess.js';
-export * from './ConfigLoader.js';
+export * from './ConfigLoader.js';
+export * from './current.js';

package/src/config/schema.ts

@@ -11,6 +11,9 @@ const providerConfig = z
 
 export const nexusConfigSchema = z.object({
   env: z.enum(['development', 'production', 'test']).default('development'),
+  app: z.object({
+    name: z.string().min(1).default('nexus'),
+  }).default({ name: 'nexus' }),
   server: z.object({
     port: z.number().int().min(1).max(65535),
     host: z.string().min(1),
@@ -47,6 +50,8 @@ export const nexusConfigSchema = z.object({
       fusion: z
         .object({
           enabled: z.boolean().default(true),
+          remote: z.boolean().default(false),
+          url: z.string().default(''),
           dir: z.string().min(1),
           persist: z.boolean().default(true),
           cacheCapacity: z.number().int().positive(),
@@ -55,6 +60,8 @@ export const nexusConfigSchema = z.object({
         })
         .default({
           enabled: true,
+          remote: false,
+          url: '',
           dir: 'storage/fusion',
           persist: true,
           cacheCapacity: 10_000,
@@ -102,18 +109,21 @@ export const nexusConfigSchema = z.object({
     }),
     cookieName: z.string(),
     refreshCookieName: z.string(),
+    // NOTE: clientId/clientSecret use z.coerce.string() — env coercion turns
+    // all-digit values (e.g. numeric Meta App IDs) into numbers, and OAuth
+    // credential fields must accept them rather than crash the boot.
     google: z
       .object({
-        clientId: z.string(),
-        clientSecret: z.string(),
+        clientId: z.coerce.string(),
+        clientSecret: z.coerce.string(),
         callbackPath: z.string(),
         scope: z.string(),
       })
       .optional(),
     facebook: z
       .object({
-        clientId: z.string(),
-        clientSecret: z.string(),
+        clientId: z.coerce.string(),
+        clientSecret: z.coerce.string(),
         callbackPath: z.string(),
         scope: z.string(),
       })
@@ -151,11 +161,11 @@ export const nexusConfigSchema = z.object({
   }),
   ads: z.object({
     enabled: z.boolean(),
-    developerToken: z.string(),
+    publisherId: z.string(),
     clientId: z.string(),
     clientSecret: z.string(),
     refreshToken: z.string(),
-    customerId: z.string(),
+    accountId: z.string().optional(),
   }),
   webrtc: z.object({
     rtcMinPort: z.number().int().min(1).max(65535),
@@ -201,14 +211,8 @@ export const nexusConfigSchema = z.object({
     host: z.string().min(1),
     enabled: z.boolean(),
   }),
-  fusion: z.object({
-    dir: z.string().min(1).default('storage/fusion'),
-    persist: z.boolean().default(true),
-    cacheCapacity: z.number().int().positive().default(10_000),
-    cacheTtlMs: z.number().int().positive().default(5_000),
-    walCompactThreshold: z.number().int().positive().default(1_000),
-  }),
   cache: z.object({
+    active: z.enum(['fusion', 'redis']).default('fusion'),
     dir: z.string().min(1).default('storage/fusion/cache'),
     persist: z.boolean().default(true),
     cacheCapacity: z.number().int().positive().default(10_000),

package/src/config/types.ts

@@ -8,6 +8,16 @@
 
 export type Env = 'development' | 'production' | 'test';
 
+/**
+ * Project identity. `app.name` is the single source of truth for the project
+ * slug; cookie names, JWT issuer/audience, redis key prefix and mail `from`
+ * are derived from it when not set explicitly.
+ */
+export interface AppConfig {
+  /** Project slug, e.g. 'nexus-bhooai-com'. Derives auth identity + namespaces. */
+  name: string;
+}
+
 export interface ServerConfig {
   port: number;
   host: string;
@@ -23,7 +33,8 @@ export interface ServerConfig {
 }
 
 export interface UploadsConfig {
-  /** Directory for persisted files, relative to the project root. */
+  /** Directory for persisted files, relative to the storage root
+   *  (`createNexusApp`'s `storageRoot`, default = project root). */
   dir: string;
   /** Public URL path for upload and download requests. */
   path: string;
@@ -52,6 +63,17 @@ export interface MongoDbConfig {
 export interface FusionDbConfig {
   /** Open the Fusion engine at boot when true. Default true. */
   enabled: boolean;
+  /**
+   * Delegate to a **standalone Fusion server** instead of opening the engine
+   * in-process. When true (or when `url` is non-empty) the backend no longer
+   * owns `storage/fusion/fusion.wal`; every read/write goes over HTTP to the
+   * `fusion` service started by `nexus dev`. This lets several apps share one
+   * Fusion database and keeps the backend process free of the Rust engine.
+   */
+  remote: boolean;
+  /** Standalone Fusion server base URL, e.g. `http://127.0.0.1:5000`.
+   *  Empty (and `remote: false`) keeps the embedded in-process engine. */
+  url: string;
   /** Durable storage dir, relative to the project root. Omit/empty for in-memory. */
   dir: string;
   /** Persist the WAL to `dir` (persist=false runs purely in-memory). */
@@ -165,11 +187,11 @@ export interface CertsConfig {
 
 export interface AdsConfig {
   enabled: boolean;
-  developerToken: string;
+  publisherId: string;
   clientId: string;
   clientSecret: string;
   refreshToken: string;
-  customerId: string;
+  accountId?: string;
 }
 
 export interface WebRtcConfig {
@@ -303,22 +325,14 @@ export interface AppPortConfig {
   enabled?: boolean;
 }
 
-export interface FusionConfig {
-  /** Durable storage dir, resolved against the backend's projectRoot. Empty or
-   *  persist=false runs the engine purely in-memory. Default 'storage/fusion'. */
-  dir: string;
-  /** When false, ignore `dir` and run purely in-memory. Default true. */
-  persist: boolean;
-  /** L1 cache capacity (entries). Default 10_000. */
-  cacheCapacity: number;
-  /** L1 cache TTL in ms. Default 5_000. */
-  cacheTtlMs: number;
-  /** WAL compaction threshold (records). Default 1_000. */
-  walCompactThreshold: number;
-}
-
 /** Redis-like FusionCache settings (`@bhooai/nexus-fusion/cache`). */
 export interface CacheConfig {
+  /** Which backend serves cache duties — 'fusion' (embedded, zero-dep,
+   *  default) or 'redis' (external server at `redis.url`). Override with
+   *  NEXUS_CACHE_ACTIVE. Single-instance apps are fully served by fusion
+   *  (strings/hashes/lists/sets + TTL); pick 'redis' for multi-instance
+   *  pub/sub fan-out. */
+  active: 'fusion' | 'redis';
   /** Durable storage dir, resolved against the backend's projectRoot. Cache
    *  lives in its own subdir (default 'storage/fusion/cache') so it never
    *  shares a WAL with the main fusion engine. */
@@ -339,6 +353,7 @@ export interface CacheConfig {
 
 export interface NexusConfig {
   env: Env;
+  app: AppConfig;
   server: ServerConfig;
   uploads: UploadsConfig;
   db: DbConfig;
@@ -356,7 +371,6 @@ export interface NexusConfig {
   plugins: PluginsConfig;
   frontend: FrontendConfig;
   admin: AdminConfig;
-  fusion: FusionConfig;
   cache: CacheConfig;
   /** Multi-app port layout. Empty = every service uses its section default. */
   apps: AppPortConfig[];

package/src/http/Server.ts

@@ -5,6 +5,7 @@ import { randomUUID } from 'node:crypto';
 import type { Middleware, RequestContext } from './context.js';
 import { createContext } from './context.js';
 import type { Router } from './Router.js';
+import type { NexusConfig } from '../config/types.js';
 import { NexusError, toNexusError } from '../errors.js';
 
 /** Generate a request id (overridable for tests/injection). */
@@ -33,6 +34,8 @@ export interface ServerOptions {
   renderError?: (err: unknown, ctx: RequestContext) => Promise<void> | void;
   /** Custom 404 renderer for unmatched routes. Falls back to JSON. */
   renderNotFound?: (ctx: RequestContext) => Promise<void> | void;
+  /** Loaded project config, exposed to handlers as `ctx.config`. */
+  config?: NexusConfig;
 }
 
 /**
@@ -87,6 +90,7 @@ export class NexusServer {
     const requestId = (req.headers['x-request-id'] as string) ?? newRequestId();
     res.setHeader('x-request-id', requestId);
     const ctx = createContext(req, res, requestId);
+    ctx.config = this.opts.config ?? null;
 
     try {
       await this.runPipeline(ctx);

package/src/http/context.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Socket } from 'node:net';
+import type { NexusConfig } from '../config/types.js';
 
 /** Route path parameters extracted from the URL. */
 export type Params = Record<string, string>;
@@ -26,6 +27,11 @@ export interface RequestContext {
   body: unknown;
   /** Per-request state. */
   state: State;
+  /**
+   * The loaded project config. Injected by NexusServer at request time; may be
+   * null when a context is built standalone (e.g. in tests).
+   */
+  config?: NexusConfig | null;
   /** Request id (also in headers as x-request-id). */
   requestId: string;
   /** The matched route pattern, e.g. "/users/:id". */

package/tests/config.test.ts

@@ -25,6 +25,57 @@ describe('configFromEnv', () => {
     expect((cfg as any).ai?.serverUrl).toBe('http://ai:8000');
     expect((cfg as any).ai?.server?.url).toBeUndefined();
   });
+
+  it('accepts a numeric Meta App ID for auth.facebook.clientId', () => {
+    // Env coercion turns all-digit values into numbers; the schema must
+    // coerce them back so boot does not crash (ZodError on auth.facebook.clientId).
+    const partial = configFromEnv({ NEXUS_AUTH_FACEBOOK_CLIENT_ID: '123456789012345' });
+    expect((partial as any).auth?.facebook?.clientId).toBe(123456789012345);
+    const cfg = mergeConfig({
+      auth: {
+        facebook: {
+          clientId: (partial as any).auth.facebook.clientId,
+          clientSecret: 's3cret',
+          callbackPath: '/auth/facebook/callback',
+          scope: 'email',
+        },
+      },
+    });
+    expect(cfg.auth.facebook?.clientId).toBe('123456789012345');
+  });
+});
+
+describe('app identity derivation', () => {
+  it('derives auth/redis/mongo/email identity from app.name', () => {
+    const cfg = mergeConfig({ app: { name: 'my-app' } });
+    expect(cfg.app.name).toBe('my-app');
+    expect(cfg.auth.jwt.issuer).toBe('my-app');
+    expect(cfg.auth.jwt.audience).toBe('my-app-client');
+    expect(cfg.auth.cookieName).toBe('my-app_sid');
+    expect(cfg.auth.refreshCookieName).toBe('my-app_rid');
+    expect(cfg.redis.keyPrefix).toBe('my-app:');
+    expect(cfg.db.mongodb.uri).toBe('mongodb://localhost:27017/my-app');
+    expect(cfg.email.from).toBe('no-reply@my-app.local');
+  });
+
+  it('lets an explicit mongo uri override the derived one', () => {
+    const cfg = mergeConfig({
+      app: { name: 'my-app' },
+      db: { mongodb: { uri: 'mongodb://remote:27017/custom' } },
+    });
+    expect(cfg.db.mongodb.uri).toBe('mongodb://remote:27017/custom');
+  });
+
+  it('lets an explicit value override the derived default', () => {
+    const cfg = mergeConfig({ app: { name: 'my-app' }, auth: { cookieName: 'custom_sid' } });
+    expect(cfg.auth.cookieName).toBe('custom_sid');
+    expect(cfg.auth.jwt.issuer).toBe('my-app');
+  });
+
+  it('defaults app.name to nexus when unset', () => {
+    const cfg = mergeConfig({});
+    expect(cfg.app.name).toBe('nexus');
+  });
 });
 
 describe('mergeConfig', () => {