Merge pull request #1718 from objectstack-ai/adr-0006-phase2-resolvekernel-seam

feat(adr-0006): Phase 2 — generic resolveKernel seam on HttpDispatcher

Author: os-zhuang

packages/runtime/src/http-dispatcher.kernel-resolver.test.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ADR-0006 Phase 2 — the generic `kernelResolver` seam.
+ *
+ * The dispatcher gains an optional host-injected resolver that owns
+ * per-request kernel selection. It coexists with the legacy `kernelManager`
+ * path and TAKES PRECEDENCE over it for primary routing. The framework ships
+ * no multi-tenant resolver — these tests pin the seam contract (precedence +
+ * undefined → defaultKernel fallback) that cloud's resolver plugs into.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { HttpDispatcher } from './http-dispatcher.js';
+import type { KernelResolver } from './http-dispatcher.js';
+
+/** Minimal kernel whose objectql records which instance served the request. */
+function makeKernel(tag: string) {
+    const objectql = {
+        find: vi.fn().mockResolvedValue([]),
+        getObjects: vi.fn().mockReturnValue({}),
+        registry: { getObject: vi.fn().mockReturnValue(null), getRegisteredTypes: vi.fn().mockReturnValue([]) },
+        __tag: tag,
+    };
+    const kernel: any = {
+        __tag: tag,
+        getService: (name: string) => (name === 'objectql' ? objectql : null),
+        getServiceAsync: async (name: string) => (name === 'objectql' ? objectql : null),
+        context: { getService: (name: string) => (name === 'objectql' ? objectql : null) },
+    };
+    return kernel;
+}
+
+describe('HttpDispatcher — ADR-0006 kernelResolver seam', () => {
+    it('prefers the injected kernelResolver over kernelManager for primary routing', async () => {
+        const defaultKernel = makeKernel('default');
+        const envKernel = makeKernel('env');
+
+        const resolveKernel = vi.fn(async () => envKernel);
+        const kernelResolver: KernelResolver = { resolveKernel };
+        const getOrCreate = vi.fn(async () => envKernel);
+
+        const dispatcher = new HttpDispatcher(defaultKernel, undefined, {
+            kernelResolver,
+            kernelManager: { getOrCreate } as any,
+            enforceProjectMembership: false,
+        });
+
+        await dispatcher.dispatch('GET', '/data/widget', undefined, {}, { request: {} } as any);
+
+        // The seam was consulted exactly once, with (context, defaultKernel)…
+        expect(resolveKernel).toHaveBeenCalledTimes(1);
+        expect(resolveKernel.mock.calls[0][1]).toBe(defaultKernel);
+        // …and it WON: the legacy kernelManager path was not used for routing.
+        expect(getOrCreate).not.toHaveBeenCalled();
+    });
+
+    it('falls back to defaultKernel when the resolver returns undefined', async () => {
+        const defaultKernel = makeKernel('default');
+        const resolveKernel = vi.fn(async () => undefined);
+
+        const dispatcher = new HttpDispatcher(defaultKernel, undefined, {
+            kernelResolver: { resolveKernel },
+            enforceProjectMembership: false,
+        });
+
+        // Should not throw — undefined routes to the single defaultKernel.
+        const result = await dispatcher.dispatch('GET', '/data/widget', undefined, {}, { request: {} } as any);
+        expect(resolveKernel).toHaveBeenCalledTimes(1);
+        expect(result).toBeDefined();
+    });
+
+    it('uses the legacy kernelManager path when no resolver is injected (back-compat)', async () => {
+        const defaultKernel = makeKernel('default');
+        const envKernel = makeKernel('env');
+        const getOrCreate = vi.fn(async () => envKernel);
+
+        const dispatcher = new HttpDispatcher(defaultKernel, undefined, {
+            kernelManager: { getOrCreate } as any,
+            enforceProjectMembership: false,
+        });
+
+        // Force a resolved environmentId so the kernelManager branch is taken.
+        await dispatcher.dispatch('GET', '/data/widget', undefined, {}, {
+            request: {},
+            environmentId: 'env_123',
+        } as any);
+
+        expect(getOrCreate).toHaveBeenCalledWith('env_123');
+    });
+});

packages/runtime/src/http-dispatcher.ts

@@ -52,13 +52,45 @@ export interface HttpDispatcherResult {
     result?: any; // For flexible return types or direct response objects (Response/NextResponse)
 }
 
+/**
+ * ADR-0006 generic kernel-resolution seam.
+ *
+ * A host (e.g. ObjectStack Cloud) injects a resolver to own per-request
+ * kernel selection. The framework ships NO multi-tenant implementation — all
+ * hostname→env strategy, the per-env kernel cache, and the control plane live
+ * in the host distribution (`@objectstack/objectos-runtime`). When no resolver
+ * is injected the dispatcher serves every request from its single
+ * `defaultKernel` (single-environment mode).
+ *
+ * Returning `undefined` routes the request to `defaultKernel` — resolvers use
+ * this for control-plane / unscoped / single-environment requests. This is the
+ * generic contract that, in ADR-0006 Phase 5, fully replaces the dispatcher's
+ * built-in `kernelManager` + hostname resolution; in Phase 2 it coexists with
+ * them (it merely takes precedence for primary request routing).
+ */
+export interface KernelResolver {
+    resolveKernel(
+        context: HttpProtocolContext,
+        defaultKernel: ObjectKernel,
+    ): Promise<ObjectKernel | undefined> | ObjectKernel | undefined;
+}
+
 /**
  * Optional configuration passed to the dispatcher constructor. Supports the
  * legacy `enforceProjectMembership` toggle plus the new multi-kernel
  * scheduling hook required by ADR-0003's cloud runtime mode.
  */
 export interface HttpDispatcherOptions {
     enforceProjectMembership?: boolean;
+    /**
+     * Optional generic kernel-resolution seam (ADR-0006). When present it
+     * TAKES PRECEDENCE over `kernelManager` for primary request routing: after
+     * the dispatcher resolves `context.environmentId`, it delegates per-request
+     * kernel selection to the resolver. Coexists with `kernelManager` (still
+     * used by action-route service resolution) until ADR-0006 Phase 5 retires
+     * the in-dispatcher resolution. Falls back to `resolveService('kernel-resolver')`.
+     */
+    kernelResolver?: KernelResolver;
     /**
      * Optional {@link KernelManager}. When present, the dispatcher resolves
      * `context.environmentId` first and then routes the request against the
@@ -88,6 +120,7 @@ export class HttpDispatcher {
     private envRegistry?: any; // EnvironmentDriverRegistry
     private defaultProject?: { environmentId: string; orgId?: string };
     private kernelManager?: KernelManager;
+    private kernelResolver?: KernelResolver;
     private scopeManager?: EnvironmentScopeManager;
     /**
      * When `true`, scoped data-plane routes enforce a
@@ -119,6 +152,10 @@ export class HttpDispatcher {
         this.envRegistry = envRegistry ?? resolveService('env-registry');
         this.enforceMembership = options?.enforceProjectMembership ?? true;
         this.kernelManager = options?.kernelManager ?? resolveService('kernel-manager');
+        // ADR-0006 Phase 2 seam — host-injected kernel resolver (preferred over
+        // kernelManager for primary routing when present). Optional service so
+        // single-environment / legacy hosts that register neither are unchanged.
+        this.kernelResolver = options?.kernelResolver ?? resolveService('kernel-resolver');
         this.scopeManager = options?.scopeManager ?? resolveService('scope-manager');
         // Single-project default is resolved lazily on first request — the
         // plugin that registers it (`createSingleEnvironmentPlugin`) may run
@@ -2806,7 +2843,14 @@ export class HttpDispatcher {
         // Reserved virtual id 'platform' addresses the control plane through
         // the regular project URL family — never spin up a per-project kernel
         // for it (there is no projects row to look up).
-        if (this.kernelManager && context.environmentId && context.environmentId !== 'platform') {
+        if (this.kernelResolver) {
+            // ADR-0006 Phase 2 seam: the host owns kernel selection. The
+            // resolver returns `defaultKernel` (or undefined) for platform /
+            // unscoped / single-env requests, so this branch is
+            // behavior-equivalent to the kernelManager path below for the
+            // cloud resolver (which delegates to the same KernelManager).
+            this.kernel = (await this.kernelResolver.resolveKernel(context, this.defaultKernel)) ?? this.defaultKernel;
+        } else if (this.kernelManager && context.environmentId && context.environmentId !== 'platform') {
             this.kernel = await this.kernelManager.getOrCreate(context.environmentId);
         } else {
             this.kernel = this.defaultKernel;

packages/runtime/src/index.ts

@@ -34,6 +34,9 @@ export type { SystemEnvironmentPluginConfig } from './system-environment-plugin.
 export { HttpServer } from './http-server.js';
 export { HttpDispatcher } from './http-dispatcher.js';
 export type { HttpProtocolContext, HttpDispatcherResult } from './http-dispatcher.js';
+// ADR-0006 generic kernel-resolution seam (retained framework contract; the
+// multi-tenant implementation lives in cloud `@objectstack/objectos-runtime`).
+export type { KernelResolver } from './http-dispatcher.js';
 export { MiddlewareManager } from './middleware.js';
 
 // ── Security primitives ───────────────────────────────────────────────