@bhooai/nexus-core 2.0.18 → 2.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bhooai/nexus-core",
-    "version": "2.0.18",
+    "version": "2.0.21",
     "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,12 +15,12 @@
 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';
 import { bodyParser } from '../http/bodyParser.js';
-import type { Handler, Middleware } from '../http/context.js';
+import type { Handler, Middleware, RequestContext } from '../http/context.js';
 import { discoverBackend, importDefault, type DiscoveryResult } from './discover.js';
 import type { RoutesFile, RouteDef } from './defineRoutes.js';
 import { DefaultErrorHandler, ErrorHandler } from './ErrorHandler.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';
@@ -41,9 +42,36 @@ import { registerAuthRoutes } from './authModule.js';
 import { issueCsrfToken, getCsrfToken, csrf, authToken, requireRole } from '@bhooai/nexus-auth';
 import { connect } from '@bhooai/nexus-data';
 import { ensureLicense } from '@bhooai/nexus-crypto';
-import { createGateway, createFederatedGateway, graphqlHttpHandler, getExplorerHtml, helloSubgraph, SubscriptionServer } from '@bhooai/nexus-graphql';
 import type { Subgraph, GraphQLContext } from '@bhooai/nexus-graphql';
 
+/**
+ * Lazily loaded `@bhooai/nexus-graphql` — an optional peer, not a hard
+ * dependency. Static-importing it here would make merely *loading*
+ * `@bhooai/nexus-core` (e.g. `nexus init`, which never serves GraphQL)
+ * crash when the peer isn't installed. Call sites `await graphqlApi()`
+ * instead; null means "not installed" and the gateway mount is skipped
+ * with a warning.
+ *
+ * Typed as `any` (not `typeof import(...)`) so the emitted declarations
+ * don't require the peer's types to be present for consumers.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _graphqlApi: any = undefined;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function graphqlApi(): Promise<any> {
+  if (_graphqlApi !== undefined) return _graphqlApi;
+  try {
+    _graphqlApi = await import('@bhooai/nexus-graphql');
+  } catch (e) {
+    if ((e as { code?: string })?.code === 'ERR_MODULE_NOT_FOUND') {
+      _graphqlApi = null;
+    } else {
+      throw e;
+    }
+  }
+  return _graphqlApi;
+}
+
 export interface CreateNexusAppOptions {
   /** Identifier for this backend, used in admin, telemetry, logs. */
   name?: string;
@@ -51,8 +79,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 +141,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 +179,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 +217,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 +235,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));
@@ -339,8 +395,16 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   let graphqlMounted = false;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let graphqlGateway: any = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let GraphqlSubscriptionServer: any = null;
   if (tech === 'react') {
   {
+    const gql = await graphqlApi();
+    if (!gql) {
+      console.warn(`[${name}] @bhooai/nexus-graphql is not installed — GraphQL gateway skipped (npm i @bhooai/nexus-graphql to enable).`);
+    } else {
+    const { createGateway, createFederatedGateway, graphqlHttpHandler, getExplorerHtml, helloSubgraph, SubscriptionServer } = gql;
+    GraphqlSubscriptionServer = SubscriptionServer;
     const explorerEnabled = (config.graphql as unknown as { explorer?: boolean })?.explorer ?? true;
     const helloEnabled = (config.graphql as unknown as { hello?: boolean })?.hello !== false;
     try {
@@ -386,7 +450,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: RequestContext) => ({ request: ctx, user: (ctx.state.user as GraphQLContext['user']), config: ctx.config ?? config, ...opts.graphqlContext }),
         });
         if (explorerEnabled) {
           const explorerHtml = getExplorerHtml({
@@ -433,7 +497,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: RequestContext) => ({ 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 +507,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: RequestContext) => ({ 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));
         }
@@ -453,6 +517,7 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
     }
   }
   }
+}
 
   // ------------------------------------------------------------------
   // Admin module — request log buffer, lazy DB, admin + AI proxy routes
@@ -510,6 +575,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
@@ -707,19 +773,19 @@ export async function createNexusApp(opts: CreateNexusAppOptions = {}): Promise<
   // and config.graphql.subscriptions is enabled.
   // ------------------------------------------------------------------
   const graphqlSubscriptions = (config.graphql as unknown as { subscriptions?: boolean })?.subscriptions ?? true;
-  if (graphqlGateway && graphqlSubscriptions && typeof graphqlGateway.subscribe === 'function') {
+  if (graphqlGateway && GraphqlSubscriptionServer && graphqlSubscriptions && typeof graphqlGateway.subscribe === 'function') {
     try {
       const subPath = `${config.graphql?.path ?? '/graphql'}/ws`;
-      new SubscriptionServer({ httpServer: server.httpServer, gateway: graphqlGateway, path: subPath });
+      new GraphqlSubscriptionServer({ httpServer: server.httpServer, gateway: graphqlGateway, path: subPath });
       console.log(`[${name}] GraphQL subscriptions mounted at ${subPath}`);
     } catch (err) {
       console.warn(`[${name}] failed to mount GraphQL subscriptions:`, err);
     }
   }
 
-  // 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';