refactor(route-parity): honest standalone hono discovery + document MCP lockstep; broaden gate

Follow-ups on the route-parity work (#3369):

- hono-server: the standalone `registerDiscoveryAndCrudEndpoints` discovery
  advertised metadata/packages/analytics/workflow/automation/ai/notifications/
  i18n/storage/ui — none of which HonoServerPlugin mounts on its own — so a
  truly standalone deployment advertised a dozen routes that 404. It now
  advertises ONLY what it mounts (the `/data` CRUD surface + the `/auth/me/*`
  helpers). Under `os serve` this fallback is shadowed by the dispatcher/REST
  service-aware discovery, so real deployments are unaffected; the fix closes
  the literal `declared !== enforced` gap the issue cited (hono-plugin.ts).

- http-dispatcher: document WHY `routes.mcp` is advertised on the
  `isMcpServerEnabled()` flag rather than gated on service presence like every
  other route — it is a deliberate LOCKSTEP (#2698): `os serve` auto-loads
  plugin-mcp from the same flag, and `@objectstack/rest` advertises mcp from
  the identical single source, so the two discovery producers stay symmetric
  and an advertised `/mcp` always has a mounted handler. Comment-only; no
  behaviour change (avoids forking the dispatcher from REST).

- route-parity gate: assert the standalone-hono honesty and note that
  REST-owned routes (/data,/meta,/ui) are covered by the @objectstack/client
  integration suite (booting a real hono server with the full dependency
  graph), so this gate stays focused on the dispatcher↔hono seam where the
  #3361/#3362/MCP regressions lived.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015si15Q1KWMKpVQWYsEvgcS

Author: claude

packages/plugins/plugin-hono-server/src/hono-plugin.test.ts

@@ -131,6 +131,38 @@ describe('HonoServerPlugin', () => {
         expect(routes['POST /api/v1/batch']).toBeUndefined();
     });
 
+    it('standalone discovery advertises ONLY the routes it actually mounts (declared === enforced, #3369)', async () => {
+        // Regression: this static discovery used to advertise metadata /
+        // packages / analytics / workflow / automation / ai / notifications /
+        // i18n / storage / ui — none of which HonoServerPlugin mounts on its own
+        // — so a standalone deployment advertised a dozen routes that 404. It
+        // must now list only the `/data` CRUD surface + the `/auth/me/*` helpers
+        // this plugin actually serves. (Under `os serve` the dispatcher/REST
+        // service-aware discovery shadows this fallback.)
+        const plugin = new HonoServerPlugin({ registerStandardEndpoints: true });
+        await plugin.init(context as PluginContext);
+        const routes: Record<string, any> = {};
+        const rawApp = {
+            get: vi.fn((path: string, h: any) => { routes[`GET ${path}`] = h; }),
+            post: vi.fn((path: string, h: any) => { routes[`POST ${path}`] = h; }),
+            use: vi.fn(),
+        };
+        (plugin as any).server.getRawApp = () => rawApp;
+        (plugin as any).registerDiscoveryAndCrudEndpoints(context);
+
+        const disc = routes['GET /api/v1/discovery']({ json: (x: any) => x }).data;
+        // Advertised: exactly the namespaces with live handlers here.
+        expect(disc.routes.data).toBe('/api/v1/data');
+        expect(disc.routes.auth).toBe('/api/v1/auth');
+        // NOT advertised: routes this standalone surface does not mount.
+        for (const dead of ['metadata', 'packages', 'analytics', 'workflow', 'automation', 'ai', 'notifications', 'i18n', 'storage', 'ui', 'realtime']) {
+            expect(disc.routes[dead], `discovery must not advertise ${dead} (not mounted here)`).toBeUndefined();
+        }
+        // Every advertised route must have a matching registered handler.
+        const registered = new Set(Object.keys(routes).map((k) => k.split(' ')[1]));
+        expect([...registered].some((p) => p.startsWith('/api/v1/data'))).toBe(true);
+    });
+
     it('should configure static files and SPA fallback when enabled', async () => {
         const plugin = new HonoServerPlugin({
             staticRoot: './public',

packages/plugins/plugin-hono-server/src/hono-plugin.ts

@@ -737,26 +737,32 @@ export class HonoServerPlugin implements Plugin {
         const rawApp = this.server.getRawApp();
         const prefix = '/api/v1';
 
-        // Build the standard discovery response
+        // Build the standard discovery response.
+        //
+        // `declared === enforced` (#3369): advertise ONLY the routes THIS plugin
+        // actually mounts below (the `/data` CRUD surface + the `/auth/me/*`
+        // helpers). This discovery is a STANDALONE FALLBACK — it is served only
+        // when the HonoServerPlugin runs alone. Under `os serve` / `os dev` the
+        // dispatcher (`@objectstack/runtime`) and `@objectstack/rest` register
+        // `${prefix}/discovery` FIRST (in `start()`, before this plugin's
+        // `kernel:ready` hook), so their SERVICE-AWARE discovery shadows this
+        // one and reports the full, actually-mounted surface. The prior static
+        // list here advertised `metadata`/`packages`/`analytics`/`workflow`/
+        // `automation`/`ai`/`notifications`/`i18n`/`storage`/`ui` — none of
+        // which this plugin mounts — so a truly standalone deployment
+        // advertised a dozen routes that 404 (the exact `declared !== enforced`
+        // gap #3369 closes). `realtime` was likewise (correctly) never listed
+        // (ADR-0076 D12, #2462): no `/realtime` HTTP surface exists anywhere.
         const discovery = {
             version: 'v1',
             apiName: 'ObjectStack API',
             routes: {
-                data:          `${prefix}/data`,
-                metadata:      `${prefix}/meta`,
-                auth:          `${prefix}/auth`,
-                packages:      `${prefix}/packages`,
-                analytics:     `${prefix}/analytics`,
-                // realtime deliberately absent (ADR-0076 D12, #2462): no
-                // /realtime HTTP surface is mounted anywhere — advertising
-                // it here made clients call a route that 404s.
-                workflow:      `${prefix}/workflow`,
-                automation:    `${prefix}/automation`,
-                ai:            `${prefix}/ai`,
-                notifications: `${prefix}/notifications`,
-                i18n:          `${prefix}/i18n`,
-                storage:       `${prefix}/storage`,
-                ui:            `${prefix}/ui`,
+                data: `${prefix}/data`,
+                // Only the `/auth/me/*` read helpers are mounted here (not the
+                // full better-auth `/auth` surface, which ships with the auth
+                // plugin); the namespace is advertised because it carries live
+                // handlers on this standalone server.
+                auth: `${prefix}/auth`,
             },
             capabilities: {
                 // This standalone Hono surface registers CRUD + auth only (see

packages/runtime/src/http-dispatcher.ts

@@ -1674,6 +1674,17 @@ export class HttpDispatcher {
                 // MCP (Streamable HTTP) is a default-on core capability —
                 // advertised unless OS_MCP_SERVER_ENABLED=false opts the env
                 // out. The objectui Integrations page reads this.
+                //
+                // `declared === enforced` here is guaranteed by a LOCKSTEP, not
+                // by service-presence gating like the routes above (#3369 /
+                // #2698): `os serve` auto-loads plugin-mcp from the SAME
+                // `isMcpServerEnabled()` flag that gates this advertisement, so
+                // whenever `/mcp` is advertised the handler is mounted (a key /
+                // token yields 401, never a 404/501). Kept flag-based on purpose
+                // — `@objectstack/rest` advertises `mcp` from the identical
+                // single source (rest-server.ts), so the two discovery producers
+                // stay symmetric. The route-parity gate asserts the lockstep
+                // holds (advertised ⇒ reachable, never 501).
                 mcp:           HttpDispatcher.isMcpEnabled() ? `${prefix}/mcp` : undefined,
         };
 

packages/runtime/src/route-parity.integration.test.ts

@@ -256,3 +256,12 @@ describe('Route parity: discovery is service-aware — no dead advertisement (#3
         expect(res.status).toBe(404);
     });
 });
+
+// NOTE ON SCOPE: this gate boots the dispatcher ↔ hono seam — where the
+// #3361 / #3362 / MCP-501 regressions lived (dispatcher-registered routes on
+// the hono listener). The REST-owned surface (`/data`, `/meta`, `/ui`) served
+// by `@objectstack/rest` is exercised against a real booted hono server with
+// its full dependency graph in the `@objectstack/client` integration suite
+// (`client.hono.test.ts`, `client.batch-transaction.test.ts`) — booting REST
+// from source here would require re-aliasing that entire graph and would only
+// duplicate that coverage.