feat(spec)!: remove the never-implemented GraphQL surface (#2462 follow-on)

Product decision: GraphQL is not on the plan. It was schema-only from
day one — 20+ spec config schemas, an unconditionally-501 handleGraphQL
(kernel.graphql never assigned in the monorepo), and THREE separate
mounts (dispatcher if-chain, dispatcher-plugin hono route, hono adapter)
advertising the dead endpoint: the "declared ≠ mounted ≠ implemented"
seam disease in one picture.

Removed: spec schemas/contracts/enum members (CoreServiceName,
ApiProtocolType, query dialects, graphql-playground), capability
booleans, discovery/router fields, all three runtime mounts, the
discovery advertisement, plugin-dev stubs, the now-dead
resolveRequestExecutionContext, qa conformance rows + ratchet pins +
dogfood surface cases, generated JSON-schema manifest keys + reference
docs, and handwritten doc mentions.

Kept deliberately: external-datasource 'graphql' protocol option (third
parties may speak GraphQL to us as a CLIENT) and cloud's reserved slug.
objectui's own dead 'graphql' union member noted for cross-repo cleanup.

Verified: full monorepo build+test forced, 131 tasks green (spec 6675,
core 386, runtime 647, dogfood 60, conformance 41 among them);
api-surface + json-schema manifest + reference docs regenerated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

.changeset/remove-graphql-surface.md

@@ -0,0 +1,31 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: remove the never-implemented GraphQL surface from the product plan (#2462 follow-on)
+
+GraphQL was schema-only from day one: the spec shipped 20+ config schemas
+(`GraphQLTypeConfig`, federation, persisted queries, …), the dispatcher's
+`handleGraphQL` answered 501 unconditionally (`kernel.graphql` was never
+assigned in the monorepo), and THREE separate mounts advertised the dead
+endpoint. Per the product decision, the surface is deleted rather than
+maintained:
+
+- **spec**: `api/graphql.zod.ts` + `contracts/graphql-service.ts` deleted;
+  `graphql` removed from `CoreServiceName`, `ApiProtocolType`, the
+  query-adapter dialects, `graphql-playground` from testing-UI types; the
+  `graphqlApi`/network capability booleans, discovery/router route fields
+  dropped. BREAKING for consumers referencing those exports/enum members.
+- **runtime**: `handleGraphQL`, the if-chain branch, the dispatcher-plugin
+  and hono-adapter mounts, discovery advertisement, and the now-dead
+  `resolveRequestExecutionContext` helper removed.
+- **plugin-dev**: the graphql stub family removed.
+- **qa**: authz-conformance matrix rows, ratchet high-risk id, discover
+  patterns and identity pins for the GraphQL surface retired; expression
+  ledger covers updated.
+- **NOT removed**: the `'graphql'` protocol option on external datasource
+  lookups (third-party systems may speak GraphQL) and cloud's reserved
+  slug — those are not our API surface.
+
+`/graphql` now 404s (was an unconditional 501); the anonymous-deny posture
+matrix shrinks by the two GraphQL rows.

content/docs/plugins/anatomy.mdx

@@ -90,7 +90,7 @@ ObjectStack uses `type` discrimination to optimize runtime behavior, allowing th
 
 ### 5. Server Plugin (`server`)
 *   **Role:** Protocol Gateway.
-*   **Use Cases:** REST API (`plugin-hono-server`), GraphQL, WebSocket.
+*   **Use Cases:** REST API (`plugin-hono-server`), WebSocket.
 *   **Behavior:** Responsible for binding ports and mapping incoming traffic.
 
 ### 6. Theme Plugin (`theme`)

content/docs/plugins/development.mdx

@@ -21,7 +21,7 @@ A plugin is a self-contained module that extends the ObjectStack kernel with:
 - **Hooks** — React to lifecycle events (before/after record create, update, delete)
 - **Objects** — Register new data objects and fields
 - **UI Components** — Add custom views, widgets, or actions
-- **API Endpoints** — Expose new REST or GraphQL endpoints
+- **API Endpoints** — Expose new REST endpoints
 
 ---
 

content/docs/references/api/discovery.mdx

@@ -51,7 +51,6 @@ const result = ApiRoutes.parse(data);
 | **automation** | `string` | optional | e.g. /api/v1/automation |
 | **storage** | `string` | optional | e.g. /api/v1/storage |
 | **analytics** | `string` | optional | e.g. /api/v1/analytics |
-| **graphql** | `string` | optional | e.g. /graphql |
 | **packages** | `string` | optional | e.g. /api/v1/packages |
 | **workflow** | `string` | optional | e.g. /api/v1/workflow |
 | **approvals** | `string` | optional | e.g. /api/v1/approvals |
@@ -76,7 +75,7 @@ const result = ApiRoutes.parse(data);
 | **locale** | `{ default: string; supported: string[]; timezone: string }` | ✅ |  |
 | **services** | `Record<string, { enabled: boolean; status: Enum<'available' \| 'registered' \| 'unavailable' \| 'degraded' \| 'stub'>; handlerReady?: boolean; route?: string; … }>` | ✅ | Per-service availability map keyed by CoreServiceName |
 | **capabilities** | `Record<string, { enabled: boolean; features?: Record<string, boolean>; description?: string }>` | optional | Hierarchical capability descriptors for frontend intelligent adaptation |
-| **schemaDiscovery** | `{ openapi?: string; graphql?: string; jsonSchema?: string }` | optional | Schema discovery endpoints for API toolchain integration |
+| **schemaDiscovery** | `{ openapi?: string; jsonSchema?: string }` | optional | Schema discovery endpoints for API toolchain integration |
 | **metadata** | `Record<string, any>` | optional | Custom metadata key-value pairs for extensibility |
 
 

content/docs/references/api/dispatcher.mdx

@@ -51,7 +51,7 @@ const result = DispatcherConfig.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **routes** | `{ prefix: string; service: Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'graphql' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui' \| 'workflow'>; authRequired: boolean; criticality: Enum<'required' \| 'core' \| 'optional'>; … }[]` | ✅ | Route-to-service mappings |
+| **routes** | `{ prefix: string; service: Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui' \| 'workflow'>; authRequired: boolean; criticality: Enum<'required' \| 'core' \| 'optional'>; … }[]` | ✅ | Route-to-service mappings |
 | **fallback** | `Enum<'404' \| 'proxy' \| 'custom'>` | ✅ | Behavior when no route matches |
 | **proxyTarget** | `string` | optional | Proxy target URL when fallback is "proxy" |
 
@@ -91,7 +91,7 @@ const result = DispatcherConfig.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **prefix** | `string` | ✅ | URL path prefix for routing (e.g. /api/v1/data) |
-| **service** | `Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'graphql' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui' \| 'workflow'>` | ✅ | Target core service name |
+| **service** | `Enum<'metadata' \| 'data' \| 'auth' \| 'file-storage' \| 'search' \| 'cache' \| 'queue' \| 'automation' \| 'analytics' \| 'realtime' \| 'job' \| 'notification' \| 'ai' \| 'i18n' \| 'ui' \| 'workflow'>` | ✅ | Target core service name |
 | **authRequired** | `boolean` | ✅ | Whether authentication is required |
 | **criticality** | `Enum<'required' \| 'core' \| 'optional'>` | ✅ | Service criticality level for unavailability handling |
 | **permissions** | `string[]` | optional | Required permissions for this route namespace |

content/docs/references/api/documentation.mdx

@@ -9,7 +9,7 @@ API Documentation & Testing Interface Protocol
 
 Provides schemas for generating interactive API documentation and testing
 
-interfaces similar to Swagger UI, GraphQL Playground, Postman, etc.
+interfaces similar to Swagger UI, Postman, etc.
 
 Features:
 
@@ -29,8 +29,6 @@ Architecture Alignment:
 
 - Postman: API testing collections
 
-- GraphQL Playground: GraphQL-specific testing
-
 - Redoc: Documentation rendering
 
 @example Documentation Config
@@ -102,7 +100,7 @@ const result = ApiChangelogEntry.parse(data);
 | **version** | `string` | ✅ | API version |
 | **description** | `string` | optional | API description |
 | **servers** | `{ url: string; description?: string; variables?: Record<string, { default: string; description?: string; enum?: string[] }> }[]` | ✅ | API server URLs |
-| **ui** | `{ type: Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphql-playground' \| 'graphiql' \| 'postman' \| 'custom'>; path: string; theme: Enum<'light' \| 'dark' \| 'auto'>; enableTryItOut: boolean; … }` | optional | Testing UI configuration |
+| **ui** | `{ type: Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphiql' \| 'postman' \| 'custom'>; path: string; theme: Enum<'light' \| 'dark' \| 'auto'>; enableTryItOut: boolean; … }` | optional | Testing UI configuration |
 | **generateOpenApi** | `boolean` | ✅ | Generate OpenAPI 3.0 specification |
 | **generateTestCollections** | `boolean` | ✅ | Generate API test collections |
 | **testCollections** | `{ name: string; description?: string; variables: Record<string, any>; requests: { name: string; description?: string; method: Enum<'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE' \| 'HEAD' \| 'OPTIONS'>; url: string; … }[]; … }[]` | ✅ | Predefined test collections |
@@ -158,7 +156,7 @@ const result = ApiChangelogEntry.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphql-playground' \| 'graphiql' \| 'postman' \| 'custom'>` | ✅ | Testing UI implementation |
+| **type** | `Enum<'swagger-ui' \| 'redoc' \| 'rapidoc' \| 'stoplight' \| 'scalar' \| 'graphiql' \| 'postman' \| 'custom'>` | ✅ | Testing UI implementation |
 | **path** | `string` | ✅ | URL path for documentation UI |
 | **theme** | `Enum<'light' \| 'dark' \| 'auto'>` | ✅ | UI color theme |
 | **enableTryItOut** | `boolean` | ✅ | Enable interactive API testing |
@@ -183,7 +181,6 @@ const result = ApiChangelogEntry.parse(data);
 * `rapidoc`
 * `stoplight`
 * `scalar`
-* `graphql-playground`
 * `graphiql`
 * `postman`
 * `custom`