feat(adr-0006)!: Phase 5 — env resolution converges into the KernelResolver seam

BREAKING CHANGE (ADR-0006 Phase 5, final phase): the framework dispatcher
no longer performs ANY multi-tenant environment resolution. The ~150-line
`resolveEnvironmentContext` (URL → hostname → x-environment-id → session
activeEnv → org default-env → single-env default, all via an environment
registry) moved to the cloud distribution's resolver
(@objectstack/objectos-runtime kernel-resolver.ts), behind the generic
`KernelResolver` seam introduced in Phase 2.

Dispatcher now:
- contributes parsing hints only: `context.routePath` + unvalidated
  `context.urlEnvironmentId` (URL conventions stay framework-owned);
- delegates env resolution + kernel selection to the host resolver, which
  SETS context.environmentId/dataDriver (membership enforcement, scope TTL
  touch and scoped service resolution key off them, unchanged);
- serves single-environment hosts from defaultKernel with no env context.

Removed from the public API:
- HttpDispatcherOptions.kernelManager (+ the 'kernel-manager' service
  pickup for routing; the SERVICE remains a cloud-side concern),
- the dispatcher's envRegistry constructor wiring (positional param kept,
  ignored, so 3-arg callers compile),
- `EnvironmentDriverRegistry` / `KernelManager` type exports +
  runtime/src/cloud/environment-registry.ts (the last file of the cloud/
  dir — directory gone; cloud owns its own copies),
- @objectstack/hono createHonoApp envRegistry/kernelManager passthroughs
  (options kept as deprecated-ignored for source compat).

handleData's 428 "environment not resolved" guard now keys off a
registered kernel-resolver (was: env-registry service) — same multi-tenant
signal, same behavior.

The dispatcher's resolution test suite moved with the behavior — ported to
cloud packages/objectos-runtime/src/kernel-resolver.test.ts (incl. the
URL-param precedence / /cloud-skip / header-fallthrough cases).

Validation: full-repo build sweep clean; runtime 368 + cli 240 + rest 100
+ hono 67 tests green; cloud repo against this checkout: boot-smoke ALL
GREEN, objectos-runtime 85 tests, typecheck clean (objectos / ee / cloud),
live file-mode HTTP behavior identical (data 401 via requireAuth after
hostname resolution through the cloud resolver).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

content/docs/references/ui/dashboard.mdx

@@ -108,6 +108,7 @@ Dashboard header action
 | **values** | `string[]` | ✅ | Measure names — Y (at least one) |
 | **layout** | `Object` | ✅ | Grid layout position |
 | **options** | `any` | optional | Widget specific configuration |
+| **suppressWarnings** | `string[]` | optional | Build diagnostic rule ids suppressed on this widget |
 | **responsive** | `Object` | optional | Responsive layout configuration |
 | **aria** | `Object` | optional | ARIA accessibility attributes |
 

packages/adapters/hono/src/index.ts

@@ -60,17 +60,14 @@ export interface ObjectStackHonoOptions {
   /** CORS configuration. Set to `false` to disable entirely. */
   cors?: ObjectStackHonoCorsOptions | false;
   /**
-   * Optional {@link KernelManager}. When provided, the dispatcher will route
-   * per-project requests to a project-scoped kernel resolved via
-   * `kernelManager.getOrCreate(environmentId)`. When absent (self-hosted mode),
-   * all requests use the single `kernel` passed above.
+   * @deprecated RETIRED (ADR-0006 Phase 5) — ignored. Multi-tenant routing is
+   * owned by the host's `KernelResolver` (registered as the
+   * `kernel-resolver` kernel service); the dispatcher picks it up there.
    */
   kernelManager?: KernelManager;
   /**
-   * Optional {@link EnvironmentDriverRegistry}. When provided, the dispatcher
-   * resolves incoming requests to a project via hostname / `X-Environment-Id`
-   * header / session before invoking the KernelManager. Required for
-   * host-based routing in cloud / multi-environment mode.
+   * @deprecated RETIRED (ADR-0006 Phase 5) — ignored. Environment resolution
+   * is owned by the host's `KernelResolver` (`kernel-resolver` service).
    */
   envRegistry?: EnvironmentDriverRegistry;
 }
@@ -114,11 +111,11 @@ export function objectStackMiddleware(kernel: ObjectKernel) {
 export function createHonoApp(options: ObjectStackHonoOptions): Hono {
   const app = new Hono();
   const prefix = options.prefix || '/api';
-  const dispatcher = new HttpDispatcher(
-    options.kernel,
-    options.envRegistry,
-    options.kernelManager ? { kernelManager: options.kernelManager } : undefined,
-  );
+  // ADR-0006 Phase 5: env resolution + multi-kernel routing belong to the
+  // host's KernelResolver (the dispatcher resolves the `kernel-resolver`
+  // service itself). The legacy envRegistry/kernelManager options are
+  // accepted-but-ignored for source compatibility.
+  const dispatcher = new HttpDispatcher(options.kernel);
 
   // ─── CORS Middleware ──────────────────────────────────────────────────────
   // Enabled by default. Controlled via options.cors or environment variables:

packages/runtime/src/cloud/environment-registry.ts

@@ -1,18 +1,20 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * ADR-0006 Phase 2 — the generic `kernelResolver` seam.
+ * ADR-0006 — the generic `kernelResolver` seam (Phase 5 semantics).
  *
- * 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.
+ * The host's resolver owns per-request ENVIRONMENT RESOLUTION + kernel
+ * selection: the dispatcher contributes parsing hints (`context.routePath`,
+ * `context.urlEnvironmentId`), expects the resolver to set
+ * `context.environmentId` / `context.dataDriver`, and serves from
+ * `defaultKernel` when the resolver returns undefined or none is registered.
+ * The framework ships no multi-tenant resolver — strategy coverage lives in
+ * cloud `packages/objectos-runtime/src/kernel-resolver.test.ts`.
  */
 
 import { describe, it, expect, vi } from 'vitest';
 import { HttpDispatcher } from './http-dispatcher.js';
-import type { KernelResolver } from './http-dispatcher.js';
+import type { KernelResolver, HttpProtocolContext } from './http-dispatcher.js';
 
 /** Minimal kernel whose objectql records which instance served the request. */
 function makeKernel(tag: string) {
@@ -32,27 +34,45 @@ function makeKernel(tag: string) {
 }
 
 describe('HttpDispatcher — ADR-0006 kernelResolver seam', () => {
-    it('prefers the injected kernelResolver over kernelManager for primary routing', async () => {
+    it('delegates kernel selection to the resolver with parsing hints attached', 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 resolveKernel = vi.fn(async (ctx: HttpProtocolContext) => {
+            // Phase 5 contract: the resolver sets the environment context.
+            ctx.environmentId = 'env-from-resolver';
+            return envKernel;
+        });
         const dispatcher = new HttpDispatcher(defaultKernel, undefined, {
-            kernelResolver,
-            kernelManager: { getOrCreate } as any,
+            kernelResolver: { resolveKernel },
             enforceProjectMembership: false,
         });
 
-        await dispatcher.dispatch('GET', '/data/widget', undefined, {}, { request: {} } as any);
+        const context: any = { request: { headers: { host: 'tenant.example.com' } } };
+        await dispatcher.dispatch('GET', '/environments/env-123/data/widget', undefined, {}, context);
 
-        // The seam was consulted exactly once, with (context, defaultKernel)…
         expect(resolveKernel).toHaveBeenCalledTimes(1);
+        const passed = resolveKernel.mock.calls[0][0] as HttpProtocolContext;
+        // Dispatcher-provided hints (pure parsing, unvalidated):
+        expect(passed.routePath).toBe('/environments/env-123/data/widget');
+        expect(passed.urlEnvironmentId).toBe('env-123');
+        // Resolver-set environment context survives for downstream stages:
+        expect(context.environmentId).toBe('env-from-resolver');
         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('does not parse /cloud/environments/:id as a scoped-path candidate', async () => {
+        const defaultKernel = makeKernel('default');
+        const resolveKernel = vi.fn(async () => undefined);
+        const dispatcher = new HttpDispatcher(defaultKernel, undefined, {
+            kernelResolver: { resolveKernel },
+            enforceProjectMembership: false,
+        });
+
+        const context: any = { request: {} };
+        await dispatcher.dispatch('GET', '/cloud/environments/env-9', undefined, {}, context);
+        const passed = resolveKernel.mock.calls[0][0] as HttpProtocolContext;
+        expect(passed.urlEnvironmentId).toBeUndefined();
     });
 
     it('falls back to defaultKernel when the resolver returns undefined', async () => {
@@ -64,28 +84,21 @@ describe('HttpDispatcher — ADR-0006 kernelResolver seam', () => {
             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 () => {
+    it('serves single-environment hosts (no resolver) from defaultKernel without env context', 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');
+        const context: any = { request: { headers: { host: 'localhost' } } };
+        const result = await dispatcher.dispatch('GET', '/data/widget', undefined, {}, context);
+        expect(result).toBeDefined();
+        // No resolver registered → nothing resolves an environment.
+        expect(context.environmentId).toBeUndefined();
     });
 });

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

@@ -1651,71 +1651,11 @@ describe('HttpDispatcher', () => {
         });
     });
 
-    // ------------------------------------------------------------------
-    // Phase 2 — URL-param project resolution
-    // ------------------------------------------------------------------
-    describe('resolveEnvironmentContext — URL-param environmentId', () => {
-        let envDispatcher: HttpDispatcher;
-        let envRegistry: any;
+    // NOTE (ADR-0006 Phase 5): the `resolveEnvironmentContext` suite that
+    // lived here moved with the behavior — environment resolution is owned
+    // by the host's KernelResolver now. Equivalent coverage:
+    //   cloud packages/objectos-runtime/src/kernel-resolver.test.ts
 
-        beforeEach(() => {
-            envRegistry = {
-                resolveByHostname: vi.fn().mockResolvedValue(null),
-                resolveById: vi.fn(),
-            };
-            envDispatcher = new HttpDispatcher(kernel, envRegistry);
-        });
-
-        it('resolves environmentId from /projects/:id/... path before hostname / header', async () => {
-            envRegistry.resolveById = vi.fn().mockResolvedValue({ name: 'driver-for-proj-123' });
-
-            const context: any = { request: { headers: { host: 'anyhost' } } };
-            // Access the private resolver through a public entry point: handleData
-            // triggers resolveEnvironmentContext with the given path.
-            await (envDispatcher as any).resolveEnvironmentContext(
-                context,
-                '/api/v1/environments/proj-123/data/task',
-            );
-
-            expect(envRegistry.resolveById).toHaveBeenCalledWith('proj-123');
-            expect(context.environmentId).toBe('proj-123');
-            expect(context.dataDriver).toEqual({ name: 'driver-for-proj-123' });
-            // Hostname path should NOT have been tried.
-            expect(envRegistry.resolveByHostname).not.toHaveBeenCalled();
-        });
-
-        it('does not treat /cloud/environments/:id as a scoping prefix', async () => {
-            envRegistry.resolveById = vi.fn().mockResolvedValue({ name: 'wrong' });
-
-            const context: any = { request: { headers: {} } };
-            await (envDispatcher as any).resolveEnvironmentContext(
-                context,
-                '/api/v1/cloud/environments/proj-123',
-            );
-
-            // /cloud is explicitly skipped.
-            expect(envRegistry.resolveById).not.toHaveBeenCalled();
-            expect(context.environmentId).toBeUndefined();
-        });
-
-        it('falls through to header resolution when URL-param project is unknown', async () => {
-            envRegistry.resolveById = vi.fn()
-                .mockResolvedValueOnce(null) // URL-param lookup fails
-                .mockResolvedValueOnce({ name: 'header-driver' }); // header lookup succeeds
-
-            const context: any = {
-                request: { headers: { 'x-environment-id': 'proj-header' } },
-            };
-            await (envDispatcher as any).resolveEnvironmentContext(
-                context,
-                '/api/v1/environments/proj-unknown/data/task',
-            );
-
-            expect(envRegistry.resolveById).toHaveBeenNthCalledWith(1, 'proj-unknown');
-            expect(envRegistry.resolveById).toHaveBeenNthCalledWith(2, 'proj-header');
-            expect(context.environmentId).toBe('proj-header');
-        });
-    });
 
     describe('enforceProjectMembership (RBAC)', () => {
         const SYSTEM_ENVIRONMENT_ID = '00000000-0000-0000-0000-000000000001';