fix: multi-adapter API route declaration & handler coverage systemic defects

- Discovery schema: add 'registered' status, handlerReady field, RouteHealthReportSchema
- Dispatcher schema: add DispatcherErrorCode (404/405/501/503), DispatcherErrorResponseSchema, /health route
- REST API plugin: add handlerStatus field to endpoints, RouteCoverageReportSchema
- Runtime dispatcher: semantic 404/501/503 differentiation, /health handler, handlerReady in discovery
- Dispatcher plugin: semantic error in sendResult, /health handler registration
- Studio: filter service endpoints by handlerReady status (not just enabled)
- CHANGELOG: document all changes

Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/808defd6-3fd9-4cb6-89a1-78d05f3e0b10

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Discovery Schema — `ServiceStatus` enum & `handlerReady` field** — Added `'registered'`
+  status to `ServiceInfoSchema` to distinguish routes that are declared in the dispatcher
+  table but whose HTTP handler has not been verified. Added `handlerReady` boolean field
+  (default `false`) so clients can filter handler-ready services before displaying endpoints.
+- **Discovery Schema — `RouteHealthReportSchema`** — New schema for automated route/handler
+  coverage reporting at startup. Includes per-route health entries (`pass`, `fail`, `missing`,
+  `skip`) and summary counters.
+- **Dispatcher Schema — `DispatcherErrorCode` & `DispatcherErrorResponseSchema`** — Semantic
+  error codes (`404`/`405`/`501`/`503`) with machine-readable `type` field
+  (`ROUTE_NOT_FOUND`, `METHOD_NOT_ALLOWED`, `NOT_IMPLEMENTED`, `SERVICE_UNAVAILABLE`) and
+  developer-facing `hint` strings.
+- **Dispatcher Schema — `/health` route** — Added health endpoint to `DEFAULT_DISPATCHER_ROUTES`.
+- **REST API Plugin — `handlerStatus` field** — Added `handlerStatus` (`implemented`, `stub`,
+  `planned`) to `RestApiEndpointSchema` to track handler implementation readiness.
+- **REST API Plugin — `RouteCoverageReportSchema`** — Schema for adapter-generated coverage
+  reports listing every declared endpoint and its implementation status.
+
+### Fixed
+- **Runtime Dispatcher — semantic error differentiation** — `HttpDispatcher.dispatch()` now
+  returns typed 404 (`ROUTE_NOT_FOUND`) with diagnostic info instead of bare `{ handled: false }`.
+  Added `notImplemented()` (501), `serviceUnavailable()` (503), and `routeNotFound()` (404)
+  helper methods.
+- **Runtime Dispatcher — `/health` handler** — Added health endpoint returning `status`,
+  `timestamp`, `version`, and `uptime`.
+- **Runtime Dispatcher — `handlerReady` in discovery** — `getDiscoveryInfo()` now emits
+  `handlerReady: true` for services with confirmed handlers and `handlerReady: false` for
+  unavailable services.
+- **Dispatcher Plugin — semantic 404** — `sendResult()` now returns `ROUTE_NOT_FOUND` error
+  type with a hint pointing to the discovery endpoint. Added `/health` handler registration.
+- **Studio — handler-ready filtering** — `useApiDiscovery()` now checks both `enabled` and
+  `handlerReady` (or `status === 'available' | 'degraded'` for backward compatibility) before
+  displaying service endpoints in the UI.
+
 ## [4.0.1] — 2026-03-31
 
 ### Fixed

apps/studio/src/hooks/use-api-discovery.ts

@@ -227,15 +227,23 @@ export function useApiDiscovery() {
       // 2. Build service endpoints from discovery
       const serviceEndpoints: EndpointDef[] = [];
       for (const [serviceName, catalog] of Object.entries(SERVICE_ENDPOINT_CATALOG)) {
-        const serviceInfo = discoveredServices[serviceName];
+        const serviceInfo = discoveredServices[serviceName] as
+          | { enabled: boolean; status?: string; handlerReady?: boolean; route?: string }
+          | undefined;
+
+        // Only include services that are both enabled and have a handler ready.
+        // Backwards-compatible: if handlerReady is not present (older backends),
+        // fall back to status !== 'unavailable' && status !== 'stub' && status !== 'registered'.
         const isEnabled = serviceInfo?.enabled ?? false;
+        const hasHandler = serviceInfo?.handlerReady
+          ?? (serviceInfo?.status === 'available' || serviceInfo?.status === 'degraded');
 
         // Use route from discovery services, discovery routes map, or catalog default
         const routePrefix = serviceInfo?.route
           ?? discoveredRoutes[serviceName]
           ?? catalog.defaultRoute;
 
-        if (isEnabled) {
+        if (isEnabled && hasHandler) {
           serviceEndpoints.push(...buildServiceEndpoints(serviceName, routePrefix));
         }
       }

packages/runtime/src/dispatcher-plugin.ts

@@ -12,7 +12,8 @@ export interface DispatcherPluginConfig {
 }
 
 /**
- * Send an HttpDispatcherResult through IHttpResponse
+ * Send an HttpDispatcherResult through IHttpResponse.
+ * Differentiates between handled, unhandled (404), and special results.
  */
 function sendResult(result: HttpDispatcherResult, res: any): void {
     if (result.handled) {
@@ -32,7 +33,16 @@ function sendResult(result: HttpDispatcherResult, res: any): void {
             return;
         }
     }
-    res.status(404).json({ success: false, error: { message: 'Not Found', code: 404 } });
+    // Semantic 404: no route matched — include diagnostic info
+    res.status(404).json({
+        success: false,
+        error: {
+            message: 'Not Found',
+            code: 404,
+            type: 'ROUTE_NOT_FOUND',
+            hint: 'No handler matched this request. Check GET /api/v1/discovery for available routes.',
+        },
+    });
 }
 
 function errorResponse(err: any, res: any): void {
@@ -96,6 +106,16 @@ export function createDispatcherPlugin(config: DispatcherPluginConfig = {}): Plu
                 res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
             });
 
+            // ── Health ──────────────────────────────────────────────────
+            server.get(`${prefix}/health`, async (_req: any, res: any) => {
+                try {
+                    const result = await dispatcher.dispatch('GET', '/health', undefined, {}, { request: _req });
+                    sendResult(result, res);
+                } catch (err: any) {
+                    errorResponse(err, res);
+                }
+            });
+
             // ── Auth ────────────────────────────────────────────────────
             server.post(`${prefix}/auth/login`, async (req: any, res: any) => {
                 try {

packages/runtime/src/http-dispatcher.ts

@@ -59,6 +59,67 @@ export class HttpDispatcher {
         };
     }
 
+    /**
+     * 501 Not Implemented – route is declared but handler is a stub or missing.
+     */
+    private notImplemented(route: string, service?: string) {
+        return {
+            status: 501,
+            body: {
+                success: false,
+                error: {
+                    code: 501,
+                    message: `Not Implemented: ${route}`,
+                    type: 'NOT_IMPLEMENTED' as const,
+                    route,
+                    service,
+                    hint: service
+                        ? `The "${service}" service route is declared but has no handler. Install or implement the handler.`
+                        : 'This endpoint is declared but not yet implemented.',
+                },
+            },
+        };
+    }
+
+    /**
+     * 503 Service Unavailable – service exists in the route table but is currently down.
+     */
+    private serviceUnavailable(route: string, service: string) {
+        return {
+            status: 503,
+            body: {
+                success: false,
+                error: {
+                    code: 503,
+                    message: `Service Unavailable: ${service}`,
+                    type: 'SERVICE_UNAVAILABLE' as const,
+                    route,
+                    service,
+                    hint: `The "${service}" service is registered but currently unavailable. It may need to be started or a plugin installed.`,
+                },
+            },
+        };
+    }
+
+    /**
+     * 404 Route Not Found — no route is registered for this path.
+     */
+    private routeNotFound(route: string) {
+        return {
+            status: 404,
+            body: {
+                success: false,
+                error: {
+                    code: 404,
+                    message: `Route Not Found: ${route}`,
+                    type: 'ROUTE_NOT_FOUND' as const,
+                    route,
+                    hint: 'No route is registered for this path. Check the API discovery endpoint for available routes.',
+                },
+            },
+        };
+    }
+
     private ensureBroker() {
         if (!this.kernel.broker) {
             throw { statusCode: 500, message: 'Kernel Broker not available' };
@@ -133,11 +194,14 @@ export class HttpDispatcher {
         };
 
         // Build per-service status map
+        // handlerReady: true means the dispatcher has a real handler for this route.
+        // handlerReady: false with status 'registered' means the route is in the table
+        // but the handler may not exist or be a stub.
         const svcAvailable = (route?: string, provider?: string) => ({
-            enabled: true, status: 'available' as const, route, provider,
+            enabled: true, status: 'available' as const, handlerReady: true, route, provider,
         });
         const svcUnavailable = (name: string) => ({
-            enabled: false, status: 'unavailable' as const,
+            enabled: false, status: 'unavailable' as const, handlerReady: false,
             message: `Install a ${name} plugin to enable`,
         });
 
@@ -174,7 +238,7 @@ export class HttpDispatcher {
             },
             services: {
                 // Kernel-provided (always available via protocol implementation)
-                metadata:       { enabled: true, status: 'degraded' as const, route: routes.metadata, provider: 'kernel', message: 'In-memory registry; DB persistence pending' },
+                metadata:       { enabled: true, status: 'degraded' as const, handlerReady: true, route: routes.metadata, provider: 'kernel', message: 'In-memory registry; DB persistence pending' },
                 data:           svcAvailable(routes.data, 'kernel'),
                 // Plugin-provided — only available when a plugin registers the service
                 auth:           hasAuth ? svcAvailable(routes.auth) : svcUnavailable('auth'),
@@ -1207,6 +1271,19 @@ export class HttpDispatcher {
              };
         }
 
+        // 0b. Health Endpoint (GET /health)
+        if (cleanPath === '/health' && method === 'GET') {
+            return {
+                handled: true,
+                response: this.success({
+                    status: 'ok',
+                    timestamp: new Date().toISOString(),
+                    version: '1.0.0',
+                    uptime: typeof process !== 'undefined' ? process.uptime() : undefined,
+                }),
+            };
+        }
+
         // 1. System Protocols (Prefix-based)
         if (cleanPath.startsWith('/auth')) {
             return this.handleAuth(cleanPath.substring(5), method, body, context);
@@ -1265,8 +1342,11 @@ export class HttpDispatcher {
         const result = await this.handleApiEndpoint(cleanPath, method, body, query, context);
         if (result.handled) return result;
 
-        // 3. Fallback (404)
-        return { handled: false };
+        // 3. Fallback — return semantic 404 with diagnostic info
+        return {
+            handled: true,
+            response: this.routeNotFound(cleanPath),
+        };
     }
 
     /**