From f555232076bde74fdddc640e227acb7e4ee50f53 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 23 Aug 2026 13:12:46 +0000 Subject: [PATCH] docs(spec): drop stale GraphQL references and stale header provenance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `GraphQL` was retired as a product surface (packages/spec/src/api/ has zero GraphQL sources, the /graphql dispatcher route was removed, and `graphql` was never actually a CoreServiceName). Two places in the package still asserted otherwise: - CATEGORY_BLURBS.api in build-docs.ts read "REST/GraphQL contracts, ..." — drop /GraphQL and regenerate content/docs/references/index.mdx (the only file that blurb feeds — no hand-edit). - packages/spec/llms.txt (hand-kept, ships in the npm tarball) listed an IGraphQLService contract row. Deleted it — IGraphQLService is declared nowhere in packages/**/src, and unlike the neighbouring IUIService DEPRECATED row it has no replacement to point readers at. Also drops llms.txt's hand-typed `Schema Count` / `Last Updated` header lines rather than refreshing them: measured against the current tree, packages/spec now publishes 1,585 schemas across 418 test files — an order of magnitude past the stale claim — and this file has no generator to keep a refreshed number honest past the next PR that touches the package. Fixes #10834 Fixes #10833 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01RadETjNRLALFLhFA3xehZP --- .changeset/docs-graphql-stale-references.md | 14 ++++++++++++++ content/docs/references/index.mdx | 4 ++-- packages/spec/llms.txt | 3 --- packages/spec/scripts/build-docs.ts | 2 +- 4 files changed, 17 insertions(+), 6 deletions(-) create mode 100644 .changeset/docs-graphql-stale-references.md diff --git a/.changeset/docs-graphql-stale-references.md b/.changeset/docs-graphql-stale-references.md new file mode 100644 index 0000000000..7bc9a8a910 --- /dev/null +++ b/.changeset/docs-graphql-stale-references.md @@ -0,0 +1,14 @@ +--- +"@objectstack/spec": patch +--- + +**Docs:** removes stale GraphQL references and stale hand-typed header provenance from generated and hand-kept protocol docs (#10834, #10833). + +GraphQL was retired as a product surface some time ago: `packages/spec/src/api/` has zero GraphQL sources, the `/graphql` HTTP route was removed from the dispatcher (out of the product plan, #2462 follow-on), and `graphql` was never actually a `CoreServiceName` — it only ever existed as a stray entry in this table and in metadata-protocol's discovery table (see the comment above `SERVICE_PROVIDER_TABLE` in `core-services.zod.ts`). Two places in the package still asserted otherwise: + +- The generated `content/docs/references/index.mdx` API Protocol blurb read "REST/GraphQL contracts, …". The source is `CATEGORY_BLURBS.api` in `packages/spec/scripts/build-docs.ts`; fixed there and regenerated with `gen:docs` — no hand-edit to the generated `.mdx`. +- The hand-kept `packages/spec/llms.txt` (no generator; ships in the npm tarball per `files`) listed an `IGraphQLService` contract (execute, subscribe) under Service Contracts. `IGraphQLService` is declared nowhere in `packages/**/src` — verified before removal. Deleted the row rather than marking it `**DEPRECATED**` like the neighbouring `IUIService` row: that precedent fits a contract that has a replacement to point readers at; GraphQL has none — it's out of the product plan, not superseded by another contract — so a deprecation note would invent a migration path that doesn't exist. + +Also dropped this file's hand-typed `Schema Count` / `Last Updated` header lines (`171 Zod schemas, 191 test files, 5,157 tests`, `2026-02-12`) rather than refreshing them. Measured against the current tree: `packages/spec` now publishes 1,585 schemas (per the freshly generated `content/docs/references/index.mdx` root index) across 418 `*.test.ts` files — both roughly an order of magnitude past what the header claimed. Since this file has no generator (confirmed by the filer) and nothing re-verifies these numbers on change, a refreshed count would start drifting again on the very next PR that touches the package; removing the assertion is more honest than restating a number this file has no mechanism to keep true. Whether `llms.txt` should be generated at all is a larger follow-up left to the PM, not decided here. + +Graded rather than skipped: `llms.txt` ships in the `@objectstack/spec` npm tarball (`files`, enforced by `check:published-files`), so this prose change reaches consumers the same way the precedent in #10669 (`skill.tools` docblock) did. diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx index 7d7d76d704..a95ae60b70 100644 --- a/content/docs/references/index.mdx +++ b/content/docs/references/index.mdx @@ -20,7 +20,7 @@ counts are sums of the rows they head. Regenerate with | Module | Pages | Schemas | Description | | :--- | ---: | ---: | :--- | | [AI Protocol](/docs/references/ai) | 11 | 66 | Agents, tools, skills, RAG and knowledge sources, model registry, conversations. | -| [API Protocol](/docs/references/api) | 29 | 417 | REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery. | +| [API Protocol](/docs/references/api) | 29 | 417 | REST contracts, endpoints, routing, realtime, batch, discovery. | | [Automation Protocol](/docs/references/automation) | 13 | 68 | Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records. | | [Cloud Protocol](/docs/references/cloud) | 11 | 94 | Environments, packages and versions, marketplace, developer portal, tenancy. | | [Data Protocol](/docs/references/data) | 29 | 166 | Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer. | @@ -63,7 +63,7 @@ Agents, tools, skills, RAG and knowledge sources, model registry, conversations. **Source:** `packages/spec/src/api/` · **Import:** `@objectstack/spec/api` · **29 pages, 417 schemas** -REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery. +REST contracts, endpoints, routing, realtime, batch, discovery. | File | Schemas | | :--- | :--- | diff --git a/packages/spec/llms.txt b/packages/spec/llms.txt index 711aa8b603..7460dd117c 100644 --- a/packages/spec/llms.txt +++ b/packages/spec/llms.txt @@ -2,8 +2,6 @@ > **SYSTEM NOTE**: This file provides a high-level summary of the ObjectStack Protocol to help LLMs understand the codebase structure and intent. > **Version**: 3.0.0 -> **Schema Count**: 171 Zod schemas, 191 test files, 5,157 tests -> **Last Updated**: 2026-02-12 ## 1. Architecture Overview (The "Three-Layer Model") @@ -168,7 +166,6 @@ function registerObject(rawConfig: unknown) { | `IAuthService` | authenticate, authorize, validateToken | | `IAutomationService` | executeFlow, triggerWorkflow | | `IUIService` | **DEPRECATED** — use IMetadataService.getView(), .listViews(), .getEffective('view', name, { userId }) | -| `IGraphQLService` | execute, subscribe | --- diff --git a/packages/spec/scripts/build-docs.ts b/packages/spec/scripts/build-docs.ts index a7accdcafe..4bd11a52b0 100644 --- a/packages/spec/scripts/build-docs.ts +++ b/packages/spec/scripts/build-docs.ts @@ -621,7 +621,7 @@ const ROOT_INDEX_INTRO = */ const CATEGORY_BLURBS: Record = { ai: 'Agents, tools, skills, RAG and knowledge sources, model registry, conversations.', - api: 'REST/GraphQL contracts, endpoints, routing, realtime, batch, discovery.', + api: 'REST contracts, endpoints, routing, realtime, batch, discovery.', automation: 'Flows and their nodes, approvals, ETL pipelines, webhooks, state machines, execution records.', cloud: 'Environments, packages and versions, marketplace, developer portal, tenancy.', data: 'Objects, fields, queries, filters, datasources and drivers — the ObjectQL layer.',