feat(runtime): mount /analytics routes only when the capability exists (#3891 follow-through, ADR-0076 D11) (#4019)

* feat(runtime): mount /analytics routes only when the capability exists (#3891 follow-through, ADR-0076 D11)

The dispatcher plugin mounted POST /analytics/query, GET /analytics/meta
and POST /analytics/sql unconditionally, so a deployment without
@objectstack/service-analytics kept the routes in its table: PUT answered
405 + Allow: POST, advertising a method on an API that isn't there (the
POST itself has answered 404 since #3989 emptied the slot).

Mounting is now capability-conditional. Plugin start() runs after the
kernel's Phase-1 init, so service presence is authoritative:

- single-kernel, `analytics` absent: routes NOT mounted — every method
  answers the adapter's shared not-found contract, and a boot log names
  the fix (install @objectstack/service-analytics);
- single-kernel, `analytics` registered: unchanged;
- multi-tenant host (kernel-resolver wired): mounted unconditionally —
  mounts are host-global while the service lives per-project kernel, so
  presence is a per-request question answered by the analytics domain's
  existing handled:false → 404. New public
  HttpDispatcher.isMultiTenantHost() exposes the mode.

Tests: three conditional-mount cases in dispatcher-plugin.routes.test.ts
(absent / registered / multi-tenant); conformance boots gain an
analytics stub so the 405 + parity contracts keep their subject, plus a
capability-absent boot pinning "no mounts, shared 404 for every method,
sibling routes unaffected". Route-ledger row annotated (a row is an
SDK-expressibility claim, not a mount guarantee).

Completes the #3891 arc: #3989 emptied the slot, #4010 made the body
contract strict at the entry, this removes the last wire-level residue
of the uninstalled API. The hono standalone static discovery that still
hardcodes the full routes table is tracked as #4018.

Refs #3891, #3989, #4010, #4018.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017WZBR9XyhXoqKCU6qQVyjx

* docs(api): discovery sample reflects the capability-conditional analytics surface

The /api/v1 discovery example still showed the pre-#3989 picture:
analytics hardcoded in `routes` and reported available with
provider objectql on a minimal install. Show the honest minimal-install
shape instead — analytics unavailable with the install hint and omitted
from routes — which also makes the sample demonstrate the
omitted-when-uninstalled rule the paragraph below it explains.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017WZBR9XyhXoqKCU6qQVyjx

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/analytics-capability-conditional-mounting.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/runtime": minor
+---
+
+feat(runtime): mount /analytics routes only when the capability exists (#3891 follow-through, ADR-0076 D11)
+
+`createDispatcherPlugin` used to mount `POST /analytics/query`,
+`GET /analytics/meta` and `POST /analytics/sql` on the `IHttpServer`
+unconditionally — so a deployment without `@objectstack/service-analytics`
+still had the routes in its table: a `PUT` answered `405` with
+`Allow: POST`, advertising a method on an API that wasn't there (the `POST`
+itself answered 404 since #3989).
+
+The mounts are now capability-conditional. Plugin `start()` runs after the
+kernel's Phase-1 init, so service presence is authoritative:
+
+- **single-kernel mode, `analytics` not registered** — the three routes are
+  NOT mounted; every method on `/api/v1/analytics/*` answers the adapter's
+  shared not-found contract (`404 { "error": "Not found" }`), and a boot log
+  names the fix (`Install @objectstack/service-analytics`);
+- **single-kernel mode, `analytics` registered** — unchanged;
+- **multi-tenant host** (a `kernel-resolver` is wired) — mounted
+  unconditionally, because mounts are host-global while the analytics service
+  lives in each per-project kernel: capability presence is a per-request
+  question, answered by the analytics domain's existing `handled:false` → 404
+  (new public `HttpDispatcher.isMultiTenantHost()` exposes the mode).
+
+With this, the `/analytics` API surface exists exactly when the capability is
+installed — completing the #3891 arc: #3989 emptied the slot (no more
+unscoped-aggregate shim), #4010 made the body contract strict at the entry,
+and this change removes the last wire-level residue of the uninstalled API.

content/docs/api/index.mdx

@@ -109,8 +109,7 @@ Returns the full discovery manifest.
   "apiName": "ObjectStack API",
   "routes": {
     "data": "/api/v1/data",
-    "metadata": "/api/v1/meta",
-    "analytics": "/api/v1/analytics"
+    "metadata": "/api/v1/meta"
   },
   "services": {
     "metadata": {
@@ -120,7 +119,7 @@ Returns the full discovery manifest.
       "provider": "objectql"
     },
     "data": { "enabled": true, "status": "available", "route": "/api/v1/data", "provider": "objectql" },
-    "analytics": { "enabled": true, "status": "available", "route": "/api/v1/analytics", "provider": "objectql" },
+    "analytics": { "enabled": false, "status": "unavailable", "message": "Install service-analytics to enable" },
     "auth": { "enabled": false, "status": "unavailable", "message": "Install plugin-auth to enable" }
   },
   "capabilities": {
@@ -131,7 +130,7 @@ Returns the full discovery manifest.
 }
 ```
 
-Disabled/uninstalled route keys (e.g. `auth`, `workflow`) are omitted from `routes` entirely rather than set to `null`; check `services` to tell "not installed" apart from "installed but not yet mounted here."
+Disabled/uninstalled route keys (e.g. `auth`, `analytics`, `workflow`) are omitted from `routes` entirely rather than set to `null`; check `services` to tell "not installed" apart from "installed but not yet mounted here." The sample above shows a minimal install: `analytics` reports `unavailable` and advertises no route until `@objectstack/service-analytics` registers the engine — the dispatcher then also mounts `/api/v1/analytics/*` (the routes are capability-conditional; an uninstalled capability answers 404 for every method).
 
 ### `GET /.well-known/objectstack`
 

packages/qa/http-conformance/src/conformance.integration.test.ts

@@ -36,10 +36,29 @@ const ADAPTERS: AdapterCase[] = [
 /**
  * Boot the full HTTP stack (ObjectQL engine + REST generator + dispatcher
  * bridge) on the given adapter and return its base URL + kernel.
+ *
+ * `withAnalytics` (default true) registers a minimal in-memory `analytics`
+ * service so the capability-conditional `/analytics` routes mount (#3891
+ * follow-through) — the transport contracts under test (405 method mismatch,
+ * parity) need the routes to exist. Pass false to exercise the
+ * capability-absent posture: no mounts, shared 404.
  */
-async function bootStack(makePlugin: () => any) {
+async function bootStack(makePlugin: () => any, opts: { withAnalytics?: boolean } = {}) {
     const kernel = new LiteKernel();
     kernel.use(new ObjectQLPlugin());
+    if (opts.withAnalytics !== false) {
+        kernel.use({
+            name: 'com.test.analytics-stub',
+            version: '0.0.0',
+            init: (c: any) => {
+                c.registerService('analytics', {
+                    query: async () => ({ rows: [], fields: [] }),
+                    getMeta: async () => ({ cubes: [] }),
+                    generateSql: async () => ({ sql: null, params: [] }),
+                });
+            },
+        } as any);
+    }
     kernel.use(makePlugin());
     kernel.use(createRestApiPlugin({
         api: {
@@ -161,14 +180,56 @@ describe.each(ADAPTERS)('IHttpServer conformance on $label adapter', ({ makePlug
     });
 
     it('405s a method mismatch with an Allow header', async () => {
-        // /api/v1/analytics/query is registered POST-only by the bridge.
+        // /api/v1/analytics/query is registered POST-only by the bridge —
+        // mounted here because bootStack registers the analytics stub
+        // (capability-conditional since #3891 follow-through).
         const res = await fetch(`${base}/api/v1/analytics/query`, { method: 'PUT' });
         expect(res.status).toBe(405);
         expect(res.headers.get('allow')).toContain('POST');
         expect((await res.json()).code).toBe('METHOD_NOT_ALLOWED');
     });
 });
 
+/**
+ * [#3891 follow-through] Capability-conditional mounting: without an
+ * `analytics` service the routes are NOT mounted, so the path answers the
+ * adapter's shared not-found contract — for EVERY method. No 405 Allow hint
+ * may leak for an API that isn't there. Single adapter suffices: the
+ * conditional lives in the dispatcher plugin, above the adapter seam.
+ */
+describe('analytics capability-conditional mounting (no service installed)', () => {
+    let stack: { kernel: LiteKernel; base: string };
+
+    beforeAll(async () => {
+        stack = await bootStack(ADAPTERS[0].makePlugin, { withAnalytics: false });
+    }, 30_000);
+
+    afterAll(async () => {
+        if (stack?.kernel) {
+            await Promise.race([
+                stack.kernel.shutdown(),
+                new Promise<void>((resolve) => setTimeout(resolve, 10_000)),
+            ]);
+        }
+    }, 30_000);
+
+    it.each(['POST', 'PUT', 'GET'])('%s /api/v1/analytics/query answers the shared 404', async (method) => {
+        const res = await fetch(`${stack.base}/api/v1/analytics/query`, { method });
+        expect(res.status).toBe(404);
+        expect(await res.json()).toEqual({ error: 'Not found' });
+    });
+
+    it('GET /api/v1/analytics/meta answers the shared 404 too', async () => {
+        const res = await fetch(`${stack.base}/api/v1/analytics/meta`);
+        expect(res.status).toBe(404);
+    });
+
+    it('a sibling dispatcher route is still mounted (the absence is analytics-scoped)', async () => {
+        const res = await fetch(`${stack.base}/api/v1/health`);
+        expect(res.status).toBe(200);
+    });
+});
+
 /**
  * Cross-adapter parity: the SAME requests against both adapters must produce
  * the same status codes and (for JSON control-plane responses) the same body

packages/runtime/src/dispatcher-plugin.routes.test.ts

@@ -111,7 +111,62 @@ describe('createDispatcherPlugin — HTTP route registration', () => {
     const plugin = createDispatcherPlugin({ prefix: '/api/v1', securityHeaders: false });
     await plugin.start?.(makeCtx(server));
 
-    expect(routes).toContain('POST /api/v1/analytics/query');
+    expect(routes).toContain('GET /api/v1/i18n/locales');
+  });
+
+  // [#3891 follow-through] The /analytics wire surface exists only when the
+  // capability does: with no `analytics` service registered (and no
+  // kernel-resolver), the three routes are NOT mounted — the path answers the
+  // adapter's shared 404, with no 405 Allow hint for an API that isn't there.
+  describe('capability-conditional /analytics mounting', () => {
+    const ANALYTICS_ROUTES = [
+      'POST /api/v1/analytics/query',
+      'GET /api/v1/analytics/meta',
+      'POST /api/v1/analytics/sql',
+    ];
+
+    function ctxWithServices(fakeServer: any, services: Record<string, any>) {
+      const kernel = {
+        getService: (name: string) => services[name],
+        getServiceAsync: async (name: string) => services[name],
+      };
+      return {
+        getKernel: () => kernel,
+        getService: (name: string) => (name === 'http.server' ? fakeServer : undefined),
+        environmentId: undefined,
+        logger: { info() {}, warn() {}, error() {}, debug() {} },
+        hook: () => {}, on: () => {},
+      } as any;
+    }
+
+    it('does NOT mount /analytics when no analytics service is registered', async () => {
+      const { server, routes } = makeFakeServer();
+      const plugin = createDispatcherPlugin({ prefix: '/api/v1', securityHeaders: false });
+      await plugin.start?.(makeCtx(server));
+
+      for (const r of ANALYTICS_ROUTES) expect(routes).not.toContain(r);
+    });
+
+    it('mounts /analytics when the analytics service is registered', async () => {
+      const { server, routes } = makeFakeServer();
+      const plugin = createDispatcherPlugin({ prefix: '/api/v1', securityHeaders: false });
+      await plugin.start?.(ctxWithServices(server, { analytics: { query: async () => ({ rows: [] }) } }));
+
+      for (const r of ANALYTICS_ROUTES) expect(routes).toContain(r);
+    });
+
+    it('mounts /analytics unconditionally on a multi-tenant host (kernel-resolver wired)', async () => {
+      // Host-global mounts, per-project services: presence is a per-request
+      // question the analytics domain answers (`handled:false` → 404), so the
+      // mount must not depend on the DEFAULT kernel's service registry.
+      const { server, routes } = makeFakeServer();
+      const plugin = createDispatcherPlugin({ prefix: '/api/v1', securityHeaders: false });
+      await plugin.start?.(ctxWithServices(server, {
+        'kernel-resolver': { resolveKernel: async (_ctx: any, def: any) => def },
+      }));
+
+      for (const r of ANALYTICS_ROUTES) expect(routes).toContain(r);
+    });
   });
 
   it('honours a custom prefix', async () => {

packages/runtime/src/dispatcher-plugin.ts

@@ -666,35 +666,67 @@ export function createDispatcherPlugin(config: DispatcherPluginConfig = {}): Plu
 
 
             // ── Analytics ───────────────────────────────────────────────
+            // [#3891 follow-through / ADR-0076 D11] The /analytics wire
+            // surface exists only when the capability does. Phase-1 init has
+            // completed by the time this start() runs, so in single-kernel
+            // mode "is the `analytics` service registered" is authoritative:
+            // absent ⇒ the routes are NOT mounted and the path answers the
+            // adapter's shared not-found contract — no route-table entry, no
+            // 405 Allow hint for an API that isn't there. A multi-tenant host
+            // (kernel-resolver wired) mounts unconditionally: mounts are
+            // host-global while the analytics service lives in the per-project
+            // kernel, so presence is a per-request question — answered by the
+            // analytics domain's existing `handled:false` → 404.
+            //
             // Route via dispatch() (not handleAnalytics directly) so the host
-            // dispatcher's project-aware kernel swap runs first — the per-project
-            // kernel owns the `analytics` service (registered by ObjectQLPlugin).
-            server.post(`${prefix}/analytics/query`, async (req: any, res: any) => {
+            // dispatcher's project-aware kernel swap runs first — the
+            // per-project kernel owns the `analytics` service.
+            const analyticsInstalled = dispatcher.isMultiTenantHost() || await (async () => {
+                const k: any = kernel;
                 try {
-                    const result = await dispatcher.dispatch('POST', '/analytics/query', req.body, req.query, { request: req });
-                    sendResult(result, res);
-                } catch (err: any) {
-                    errorResponse(err, res);
+                    if (k && typeof k.getServiceAsync === 'function') {
+                        const svc = await k.getServiceAsync('analytics').catch(() => undefined);
+                        if (svc) return true;
+                    }
+                    return !!k?.getService?.('analytics');
+                } catch {
+                    return false;
                 }
-            });
+            })();
 
-            server.get(`${prefix}/analytics/meta`, async (req: any, res: any) => {
-                try {
-                    const result = await dispatcher.dispatch('GET', '/analytics/meta', undefined, req.query, { request: req });
-                    sendResult(result, res);
-                } catch (err: any) {
-                    errorResponse(err, res);
-                }
-            });
+            if (analyticsInstalled) {
+                server.post(`${prefix}/analytics/query`, async (req: any, res: any) => {
+                    try {
+                        const result = await dispatcher.dispatch('POST', '/analytics/query', req.body, req.query, { request: req });
+                        sendResult(result, res);
+                    } catch (err: any) {
+                        errorResponse(err, res);
+                    }
+                });
 
-            server.post(`${prefix}/analytics/sql`, async (req: any, res: any) => {
-                try {
-                    const result = await dispatcher.dispatch('POST', '/analytics/sql', req.body, req.query, { request: req });
-                    sendResult(result, res);
-                } catch (err: any) {
-                    errorResponse(err, res);
-                }
-            });
+                server.get(`${prefix}/analytics/meta`, async (req: any, res: any) => {
+                    try {
+                        const result = await dispatcher.dispatch('GET', '/analytics/meta', undefined, req.query, { request: req });
+                        sendResult(result, res);
+                    } catch (err: any) {
+                        errorResponse(err, res);
+                    }
+                });
+
+                server.post(`${prefix}/analytics/sql`, async (req: any, res: any) => {
+                    try {
+                        const result = await dispatcher.dispatch('POST', '/analytics/sql', req.body, req.query, { request: req });
+                        sendResult(result, res);
+                    } catch (err: any) {
+                        errorResponse(err, res);
+                    }
+                });
+            } else {
+                ctx.logger?.info?.(
+                    '[dispatcher] /analytics not mounted — no `analytics` service is registered. ' +
+                    'Install @objectstack/service-analytics to enable the analytics API.',
+                );
+            }
 
             // ── MCP (Streamable HTTP) + API keys (ADR-0036) ─────────────
             // Mounted explicitly (there is no catch-all) and routed through

packages/runtime/src/http-dispatcher.ts

@@ -282,6 +282,19 @@ export class HttpDispatcher {
         getRegisteredAiRoutes: () => (this.kernel as any)?.__aiRoutes,
     };
 
+    /**
+     * Whether this dispatcher serves a multi-tenant host (a `kernel-resolver`
+     * is wired, so each request may resolve to a different per-project
+     * kernel). Consulted by the dispatcher plugin's capability-conditional
+     * route mounting (#3891 follow-through): on a multi-tenant host, route
+     * mounts are host-global while optional services live per project kernel,
+     * so "is the capability installed" is a per-request question the domain
+     * handler answers — never a mount-time one.
+     */
+    isMultiTenantHost(): boolean {
+        return !!this.kernelResolver;
+    }
+
     /**
      * ADR-0076 D11 step ③ — seed the domain registry with the domains lifted
      * out of the `dispatch()` if-chain. Bodies of the four service-backed

packages/runtime/src/route-ledger.ts

@@ -109,6 +109,10 @@ export const ROUTE_LEDGER: readonly RouteLedgerEntry[] = [
   { route: 'GET /discovery', domain: '/discovery', disposition: 'sdk', client: 'connect' },
 
   // ── analytics ─────────────────────────────────────────────────────────────
+  // Capability-conditional (#3891 follow-through): the plugin mounts these
+  // only when an `analytics` service is registered (or on a multi-tenant
+  // host). The ledger row is the SDK-expressibility claim, not a mount
+  // guarantee — see the header's "A ROW HERE IS NOT A WIRE GUARANTEE".
   { route: 'POST /analytics/query', domain: '/analytics', disposition: 'sdk', client: 'analytics.query' },
   { route: 'GET /analytics/meta', domain: '/analytics', disposition: 'sdk', client: 'analytics.meta',
     note: 'optional ?cube= filter honored server-side; was mismatch — the client called /meta/:cube, a shape no server ever mounted (#3584)' },