feat(cluster): multi-node authorization gate (open seam for EE license) (#2230)

@objectstack/service-cluster exports registerMultiNodeGate /
checkMultiNodeAllowed — a generic seam a distribution (e.g. EE) registers a
gate into to authorize multi-node (remote-driver) topology. The open
framework ships no gate: multi-node is always allowed. Zero license logic
here; this is the open mechanism an EE license plugs into (cloud ADR-0022).

os serve consults the gate before activating a remote cluster driver; on
denial it downgrades to single-node (in-memory) rather than failing —
multi-node is an add-on, never bricks the runtime. The CLI keeps using a
dynamic, non-literal import specifier so it does not statically depend on
the cluster package (mirrors the remote-driver import).

- multi-node-gate.ts: registry + checkMultiNodeAllowed + reset (5 tests).
- service-cluster build (full DTS) + 45 tests green; cli build green.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.changeset/cluster-multinode-gate.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/service-cluster": minor
+"@objectstack/cli": minor
+---
+
+feat(cluster): multi-node authorization gate (open mechanism)
+
+`@objectstack/service-cluster` now exports `registerMultiNodeGate` /
+`checkMultiNodeAllowed`: a distribution (e.g. the Enterprise Edition) can
+register a gate that authorizes whether the runtime may enable a multi-node
+(remote-driver) topology. The open framework ships no gate — multi-node is
+always allowed.
+
+`os serve` consults the gate before activating a remote cluster driver; on
+denial it **downgrades to single-node (in-memory) rather than failing** —
+multi-node is an add-on, never bricks the runtime. The framework holds zero
+license logic; this is the open seam an EE license plugs into (cloud ADR-0022).

packages/cli/src/commands/serve.ts

@@ -539,9 +539,26 @@ export default class Serve extends Command {
       let clusterConfig: { driver: string; url?: string } | undefined;
       const __clusterDriver = process.env.OS_CLUSTER_DRIVER?.trim();
       if (__clusterDriver && __clusterDriver !== 'memory') {
-        try { await import(`@objectstack/service-cluster-${__clusterDriver}`); }
-        catch { /* may already be registered by the loaded config */ }
-        clusterConfig = { driver: __clusterDriver, url: process.env.OS_REDIS_URL };
+        // Multi-node authorization gate (open mechanism): a distribution (e.g.
+        // an EE license) may deny multi-node. On denial, downgrade to
+        // single-node rather than fail — multi-node is an add-on, never brick.
+        // Dynamic, non-literal specifier so the CLI does not statically depend
+        // on the cluster package (mirrors the remote-driver import below).
+        const __clusterPkg: string = '@objectstack/service-cluster';
+        const { checkMultiNodeAllowed } = (await import(__clusterPkg)) as {
+          checkMultiNodeAllowed: () => { allowed: boolean; reason?: string };
+        };
+        const __gate = checkMultiNodeAllowed();
+        if (!__gate.allowed) {
+          console.warn(
+            `[cluster] multi-node not authorized (${__gate.reason ?? 'denied'}) — ` +
+            `downgrading to single-node (in-memory cluster). Remove OS_CLUSTER_DRIVER to silence.`,
+          );
+        } else {
+          try { await import(`@objectstack/service-cluster-${__clusterDriver}`); }
+          catch { /* may already be registered by the loaded config */ }
+          clusterConfig = { driver: __clusterDriver, url: process.env.OS_REDIS_URL };
+        }
       }
       const runtime = new Runtime({
         kernel: {

packages/services/service-cluster/src/index.ts

@@ -66,3 +66,10 @@ export type {
     CounterIncrOptions,
     ClusterCallContext,
 } from '@objectstack/spec/contracts';
+
+export {
+    registerMultiNodeGate,
+    checkMultiNodeAllowed,
+    __resetMultiNodeGate,
+    type MultiNodeGate,
+} from './multi-node-gate.js';

packages/services/service-cluster/src/multi-node-gate.test.ts

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+import { describe, it, expect, afterEach } from 'vitest';
+import {
+    registerMultiNodeGate,
+    checkMultiNodeAllowed,
+    __resetMultiNodeGate,
+} from './multi-node-gate.js';
+
+afterEach(() => __resetMultiNodeGate());
+
+describe('multi-node gate', () => {
+    it('allows when no gate is registered (open framework)', () => {
+        expect(checkMultiNodeAllowed()).toEqual({ allowed: true });
+    });
+
+    it('honors a denying gate with reason', () => {
+        registerMultiNodeGate({ allowMultiNode: () => ({ allowed: false, reason: 'unlicensed' }) });
+        expect(checkMultiNodeAllowed()).toEqual({ allowed: false, reason: 'unlicensed' });
+    });
+
+    it('honors an allowing gate', () => {
+        registerMultiNodeGate({ allowMultiNode: () => ({ allowed: true }) });
+        expect(checkMultiNodeAllowed().allowed).toBe(true);
+    });
+
+    it('last registration wins', () => {
+        registerMultiNodeGate({ allowMultiNode: () => ({ allowed: false }) });
+        registerMultiNodeGate({ allowMultiNode: () => ({ allowed: true }) });
+        expect(checkMultiNodeAllowed().allowed).toBe(true);
+    });
+
+    it('reset restores open default', () => {
+        registerMultiNodeGate({ allowMultiNode: () => ({ allowed: false }) });
+        __resetMultiNodeGate();
+        expect(checkMultiNodeAllowed()).toEqual({ allowed: true });
+    });
+});

packages/services/service-cluster/src/multi-node-gate.ts

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Multi-node authorization gate (open mechanism).
+ *
+ * The open framework ships **no gate** — multi-node is always allowed. A
+ * distribution (e.g. the Enterprise Edition) registers a gate to authorize
+ * whether the runtime may enable a multi-node (remote-driver) topology — for
+ * example, an EE license check. The framework deliberately knows nothing about
+ * *why* a gate allows or denies; it only consults the registered decision.
+ *
+ * When a gate denies, the caller (e.g. `os serve`) **downgrades to single-node**
+ * rather than failing — multi-node is an add-on, not a precondition for the
+ * runtime to serve. This is distinct from the split-brain guard, which throws
+ * on an outright misconfiguration (memory driver declared multi-node).
+ */
+export interface MultiNodeGate {
+    /**
+     * Called before the runtime enables a remote-driver (multi-node) topology.
+     * Return `allowed: false` to force single-node; `reason` is surfaced in logs.
+     */
+    allowMultiNode(): { allowed: boolean; reason?: string };
+}
+
+let registered: MultiNodeGate | undefined;
+
+/**
+ * Register the multi-node authorization gate. Last registration wins. A
+ * distribution calls this at boot (before the cluster topology is resolved).
+ */
+export function registerMultiNodeGate(gate: MultiNodeGate): void {
+    registered = gate;
+}
+
+/**
+ * Resolve the multi-node decision. With no gate registered (open framework),
+ * multi-node is allowed.
+ */
+export function checkMultiNodeAllowed(): { allowed: boolean; reason?: string } {
+    return registered ? registered.allowMultiNode() : { allowed: true };
+}
+
+/** Clear the registered gate. For tests. */
+export function __resetMultiNodeGate(): void {
+    registered = undefined;
+}