Changes before error encountered

Agent-Logs-Url: https://github.com/objectstack-ai/spec/sessions/b4c61b6c-9174-48d1-8cf4-65b626f3c81c

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

Author: Copilot

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

@@ -233,7 +233,7 @@ export function useApiDiscovery() {
 
         // 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'.
+        // treat status === 'available' or status === 'degraded' as equivalent to handlerReady: true.
         const isEnabled = serviceInfo?.enabled ?? false;
         const hasHandler = serviceInfo?.handlerReady
           ?? (serviceInfo?.status === 'available' || serviceInfo?.status === 'degraded');

packages/runtime/src/dispatcher-plugin.ts

@@ -40,7 +40,7 @@ function sendResult(result: HttpDispatcherResult, res: any): void {
             message: 'Not Found',
             code: 404,
             type: 'ROUTE_NOT_FOUND',
-            hint: 'No handler matched this request. Check GET /api/v1/discovery for available routes.',
+            hint: 'No handler matched this request. Check the API discovery endpoint for available routes.',
         },
     });
 }

packages/runtime/src/http-dispatcher.ts

@@ -152,9 +152,9 @@ 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.
+        // handlerReady: true means the dispatcher has a real, bound handler for this route.
+        // handlerReady: false means the route is present in the discovery table but may not
+        // yet have a concrete implementation or may be served by a stub.
         const svcAvailable = (route?: string, provider?: string) => ({
             enabled: true, status: 'available' as const, handlerReady: true, route, provider,
         });

packages/spec/src/api/discovery.zod.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { z } from 'zod';
+import { HttpMethod } from '../shared/http.zod';
 
 /**
  * Service Status Enum
@@ -37,16 +38,19 @@ export const ServiceInfoSchema = z.object({
   status: ServiceStatus,
   /**
    * Whether the HTTP handler for this service is confirmed to be mounted.
-   * `true`  = handler is registered in the adapter / dispatcher (safe to call).
-   * `false` = route is declared (e.g., in Discovery metadata) but no handler exists
-   *           — requests will receive 501 Not Implemented.
    *
-   * Clients SHOULD check this flag before displaying a service endpoint in the UI.
-   * @default false
+   * Semantics:
+   * - `undefined` (omitted) = handler readiness is unknown / not yet verified.
+   * - `true`                = handler is registered in the adapter / dispatcher (safe to call).
+   * - `false`               = route is declared but no handler exists or only a stub is present
+   *                            — requests are expected to receive 501 Not Implemented.
+   *
+   * Clients SHOULD check this flag before displaying or invoking a service endpoint and may
+   * distinguish between "unknown" (omitted) and "known missing" (`false`).
    */
   handlerReady: z.boolean().optional().describe(
     'Whether the HTTP handler is confirmed to be mounted. '
-    + 'Omitted or false means the route is declared but may return 501.'
+    + 'Omitted = readiness unknown/unverified; true = handler mounted; false = handler missing or stub (likely 501).'
   ),
   /** Route path (only present if enabled) */
   route: z.string().optional().describe('e.g. /api/v1/analytics'),
@@ -226,7 +230,7 @@ export const RouteHealthEntrySchema = z.object({
   /** Route path (e.g. /api/v1/analytics) */
   route: z.string().describe('Route path pattern'),
   /** HTTP method */
-  method: z.string().describe('HTTP method (GET, POST, etc.)'),
+  method: HttpMethod.describe('HTTP method (GET, POST, etc.)'),
   /** Target service name */
   service: z.string().describe('Target service name'),
   /** Whether the route is declared in discovery */

packages/spec/src/api/dispatcher.zod.ts

@@ -171,13 +171,17 @@ export const DEFAULT_DISPATCHER_ROUTES: DispatcherRouteInput[] = [
 /**
  * Semantic HTTP error codes used by the Dispatcher.
  *
- * The dispatcher MUST distinguish between these three failure modes so that
+ * The dispatcher MUST distinguish between these four failure modes so that
  * clients (and developers) can understand *why* an API call failed:
  *
  * - `404` – Route Not Found: no route is registered for this path.
  * - `405` – Method Not Allowed: route exists but the HTTP method is not supported.
  * - `501` – Not Implemented: route is declared but the handler is a stub / not yet coded.
  * - `503` – Service Unavailable: service exists but is temporarily down or not loaded.
+ *
+ * Note: These are string representations of HTTP status codes for use in enum
+ * matching. The `DispatcherErrorResponseSchema.error.code` field carries the
+ * numeric HTTP status code for direct use in HTTP responses.
  */
 export const DispatcherErrorCode = z.enum(['404', '405', '501', '503']).describe(
   '404 = route not found, 405 = method not allowed, 501 = not implemented (stub), 503 = service unavailable'

packages/spec/src/api/plugin-rest-api.zod.ts

@@ -94,6 +94,18 @@ export type RestApiRouteCategory = z.infer<typeof RestApiRouteCategory>;
 // Route Registration Schema
 // ==========================================
 
+/**
+ * Handler Implementation Status
+ * Shared enum for tracking whether an endpoint has a real handler.
+ * Used by both `RestApiEndpointSchema` and `RouteCoverageEntrySchema`.
+ *
+ * - `implemented` – A real handler is coded and registered.
+ * - `stub`        – A placeholder handler exists that returns 501 Not Implemented.
+ * - `planned`     – Declared in the protocol spec but not yet implemented.
+ */
+export const HandlerStatusSchema = z.enum(['implemented', 'stub', 'planned']);
+export type HandlerStatus = z.infer<typeof HandlerStatusSchema>;
+
 /**
  * REST API Endpoint Schema
  * Defines a single REST API endpoint with its metadata
@@ -169,7 +181,7 @@ export const RestApiEndpointSchema = z.object({
    * - `planned`     – Declared in the protocol spec but not yet implemented.
    * @default 'implemented'
    */
-  handlerStatus: z.enum(['implemented', 'stub', 'planned']).optional()
+  handlerStatus: HandlerStatusSchema.optional()
     .describe('Handler implementation status: implemented (default if omitted), stub, or planned'),
 });
 
@@ -1685,11 +1697,11 @@ export const RouteCoverageEntrySchema = z.object({
   /** Full URL path of the endpoint */
   path: z.string().describe('Full URL path (e.g. /api/v1/analytics/query)'),
   /** HTTP method */
-  method: z.string().describe('HTTP method (GET, POST, etc.)'),
+  method: HttpMethod.describe('HTTP method (GET, POST, etc.)'),
   /** Route category */
   category: RestApiRouteCategory.describe('Route category'),
   /** Handler implementation status */
-  handlerStatus: z.enum(['implemented', 'stub', 'planned']).describe('Handler status'),
+  handlerStatus: HandlerStatusSchema.describe('Handler status'),
   /** Target service */
   service: z.string().describe('Target service name'),
   /** Whether the handler was successfully called during health check */