@bhooai/nexus-core 2.0.17 → 2.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-core",
-    "version": "2.0.17",
+    "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();
 
@@ -161,7 +180,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   }
 
   // ------------------------------------------------------------------
-  // User store — Mongo (default) or Fusion (db.active: 'fusion').
+  // User store — Fusion (default) or Mongo (db.active: 'mongodb').
   // ------------------------------------------------------------------
   if (activeDatabase(config) === 'fusion') {
     if (!fusionEnabled(config)) {
@@ -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')