ts-procedures 10.0.0 → 10.1.1

package/docs/doc-envelope-spec-v1.md

@@ -0,0 +1,296 @@
+# ts-procedures DocEnvelope — Consumer Spec (`specVersion: 1`)
+
+> **This document describes DocEnvelope `specVersion: 1`.** The filename is
+> pinned to the spec version (`-v1`) so future format changes land as a sibling
+> (`doc-envelope-spec-v2.md`) and the differences stay diffable. Check the
+> envelope's `specVersion` field (absent ⇒ `1`) to know which spec applies.
+
+A spec for a GUI that fetches a `DocEnvelope` JSON document from a ts-procedures
+server URL and renders it. This is the **stable wire contract** between a
+ts-procedures server and any documentation/codegen consumer. It is a *frozen*
+contract in the framework (changing field names/nesting breaks codegen goldens),
+so you can build against it confidently.
+
+Companion file: `doc-envelope-v1.schema.json` (JSON Schema Draft-07) — validate
+fetched documents against it.
+
+---
+
+## 1. How you get the document
+
+There is **no built-in endpoint**. A server author calls
+`builder.toDocEnvelope()` (or `DocRegistry.toJSON()`) and exposes the resulting
+JSON at a route of their choosing (e.g. `GET /api/docs`, `/openapi`, a static
+`.json` file, etc.).
+
+So your website's "paste a URL" flow should:
+
+1. `fetch(url)` the user-supplied URL.
+2. Expect `Content-Type` ~ JSON; `JSON.parse` the body.
+3. Validate that it is an object with a `routes` **array**. That single check is
+   what the official codegen uses as its "is this an envelope?" gate. If
+   `routes` is missing/not-an-array, show a clear "not a ts-procedures docs
+   document" error.
+4. Optionally validate fully against `doc-envelope-v1.schema.json`.
+
+CORS: the server must allow your origin, or you'll need a proxy. Worth surfacing
+as a distinct error from "bad JSON".
+
+---
+
+## 2. Top-level shape
+
+```ts
+interface DocEnvelope {
+  specVersion?: number       // envelope wire-format version; absent ⇒ treat as 1
+  generatorVersion?: string  // producing ts-procedures version, e.g. "10.0.0" (informational)
+  basePath: string           // e.g. "/api" (may be "")
+  headers: HeaderDoc[]       // global headers (often [])
+  errors: ErrorDoc[]         // the error catalog
+  routes: AnyRouteDoc[]      // every procedure/route
+}
+```
+
+The authoritative producer (`DocRegistry.toJSON`) emits these six keys.
+Resilience notes:
+
+- **`specVersion`** is your compatibility signal — a small monotonic integer
+  that increments **only** when the envelope format changes (never on routine
+  package releases). **Branch your parser on this.** Treat a **missing**
+  `specVersion` as `1` (documents predating the field). Refuse / warn on a
+  `specVersion` higher than your GUI knows about. Current value: `1`.
+- **`generatorVersion`** is the producing ts-procedures package version (e.g.
+  `"10.0.0"`). **Informational only** — show it in a footer/tooltip, but do
+  **not** use it to decide how to parse; it changes every release regardless of
+  format. (Note: one internal codegen *input* fixture carries an unrelated
+  top-level `"version"` string and uppercase methods — that's a loose
+  hand-authored fixture, not server output; ignore `version` if you ever see it.)
+- Be tolerant of **extra top-level keys** — treat unknown keys as opaque.
+- `headers` and `errors` are commonly empty arrays. Render gracefully.
+
+---
+
+## 3. The error catalog (`errors`)
+
+```ts
+interface ErrorDoc {
+  name: string                       // unique; routes reference it by this name
+  statusCode: number                 // HTTP status, e.g. 400, 404, 418, 500
+  description: string
+  schema?: Record<string, unknown>   // JSON Schema of the error body (optional)
+}
+```
+
+Framework defaults are auto-merged and always present unless opted out:
+`ProcedureValidationError` (400), `ProcedureYieldValidationError` (500),
+`ProcedureError` (500), `ProcedureRegistrationError` (500). User taxonomy errors
+(e.g. `NotFound` 404, `Teapot` 418) appear alongside them.
+
+**GUI tip:** build a `Map<name, ErrorDoc>`. Each route's `errors: string[]` is a
+list of these names — render them as links/badges that resolve to the catalog
+entry (status code + description + body schema).
+
+---
+
+## 4. Global headers (`headers`)
+
+```ts
+interface HeaderDoc {
+  name: string
+  description?: string
+  required?: boolean
+  example?: string
+}
+```
+
+Simple list; render as a small table. Often empty.
+
+---
+
+## 5. Routes — discriminated union on `kind`
+
+`routes[]` mixes four kinds. **Always switch on `route.kind`.** Every route has a
+`name` and a `jsonSchema` object; the rest varies by kind.
+
+| `kind`          | Transport            | Path field(s)        | Method field        | Payload schema keys                          |
+|-----------------|----------------------|----------------------|---------------------|----------------------------------------------|
+| `rpc`           | JSON-RPC (POST)      | `path`               | `method: "post"`    | `body`, `response`                           |
+| `stream`        | RPC stream (SSE/text)| `path`               | `methods: string[]` | `params`, `yieldType`, `returnType`          |
+| `api`           | REST                 | `path?`, `fullPath`  | `method`            | `req.{pathParams,query,body,headers}`, `res.{body,headers}` |
+| `http-stream`   | REST stream (SSE)    | `path?`, `fullPath`  | `method`            | `req.{...}`, `res.{headers}`, `yield`, `returnType` |
+
+Common fields: `name` (string), `errors?` (string[] → catalog names),
+`scope` (grouping; `string | string[]` for rpc/stream, `string` for api/http-stream).
+
+> **No per-route `description`.** A `description` passed at procedure-definition
+> time is **not** carried into the route doc. Don't build UI that depends on it.
+
+### 5.1 `rpc`
+
+```jsonc
+{
+  "kind": "rpc",
+  "name": "GetUser",
+  "version": 1,
+  "scope": "users",
+  "path": "/api/users/get-user/1",   // full path; embeds scope + version
+  "method": "post",
+  "jsonSchema": {
+    "body":     { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } },
+    "response": { "type": "object", "required": ["id","name"], "properties": { "id":{"type":"string"}, "name":{"type":"string"} } }
+  },
+  "errors": ["Teapot"]
+}
+```
+
+- `jsonSchema.body` = request input (runtime-validated).
+- `jsonSchema.response` = response shape (documentation only).
+- Both are optional (a no-arg/no-return procedure yields `jsonSchema: {}`).
+
+### 5.2 `stream` (RPC stream)
+
+```jsonc
+{
+  "kind": "stream",
+  "name": "WatchUser",
+  "version": 2,
+  "scope": ["users", "live"],
+  "path": "/api/users/live/watch-user/2",
+  "methods": ["post", "get"],
+  "streamMode": "sse",                 // "sse" | "text"
+  "jsonSchema": {
+    "params":     { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } },
+    "yieldType":  { /* see note */ },
+    "returnType": { "type": "object", "required": ["total"], "properties": { "total": { "type": "number" } } }
+  }
+}
+```
+
+- `params` = input (query params for GET, body for POST).
+- **`yieldType` in `sse` mode is the SSE envelope**, not the bare value:
+  ```jsonc
+  {
+    "type": "object",
+    "description": "SSE message envelope. The data field contains the procedure yield value.",
+    "required": ["data", "event", "id"],
+    "properties": {
+      "data":  { /* the actual per-yield value schema */ },
+      "event": { "type": "string" },
+      "id":    { "type": "string" },
+      "retry": { "type": "number" }
+    }
+  }
+  ```
+  In `text` mode `yieldType` is the bare value schema. **GUI tip:** to show "what
+  each event carries", detect the SSE envelope (object with `data`/`event`/`id`)
+  and surface `properties.data`; otherwise show `yieldType` directly.
+- `returnType` = value delivered on stream completion (carried by the `return`
+  SSE event). Optional.
+- `errors` here are pre-stream errors only.
+
+### 5.3 `api` (REST)
+
+```jsonc
+{
+  "kind": "api",
+  "name": "UpdateUser",
+  "scope": "users",
+  "path": "/users/:id",          // as registered (may have :params)
+  "method": "put",
+  "fullPath": "/api/users/:id",  // resolved, incl. basePath — prefer this for display
+  "successStatus": 200,          // optional; defaults POST→201, DELETE→204, else 200
+  "jsonSchema": {
+    "req": {
+      "pathParams": { "type":"object", "required":["id"], "properties":{"id":{"type":"string"}} },
+      "query":      { "type":"object", "properties":{"dryRun":{"type":"boolean"}} },
+      "body":       { "type":"object", "required":["name"], "properties":{"name":{"type":"string"}} }
+      // "headers" also possible
+    },
+    "res": {
+      "body":    { "type":"object", "required":["id","name"], "properties":{"id":{"type":"string"},"name":{"type":"string"}} },
+      "headers": { "type":"object", "required":["x-rev"], "properties":{"x-rev":{"type":"string"}} }
+    }
+  },
+  "errors": ["Teapot"]
+}
+```
+
+- `req` channels: any of `pathParams`, `query`, `body`, `headers` (all optional).
+- `res` channels: `body`, `headers` (both optional).
+- `jsonSchema.req`/`res` may be `{}` or absent for trivial endpoints.
+- Prefer `fullPath` for the displayed URL; `path` may be omitted in some
+  envelopes.
+
+### 5.4 `http-stream` (REST stream)
+
+```jsonc
+{
+  "kind": "http-stream",
+  "name": "TailUser",
+  "scope": "users",
+  "path": "/users/:id/tail",
+  "method": "get",
+  "fullPath": "/api/users/:id/tail",
+  "streamMode": "sse",
+  "jsonSchema": {
+    "req":        { "pathParams": { "type":"object", "required":["id"], "properties":{"id":{"type":"string"}} } },
+    "res":        { "headers": { /* optional response headers schema */ } },
+    "yield":      { "type":"object", "required":["line"], "properties":{"line":{"type":"string"}} },
+    "returnType": { "type":"object", "required":["lines"], "properties":{"lines":{"type":"number"}} }
+  }
+}
+```
+
+- Same `req` channels as `api`.
+- `res` has **`headers` only** (no `body` — streaming responses have no single body).
+- `yield` = per-event value schema, **raw** (NOT wrapped in an SSE envelope,
+  unlike `kind: "stream"`).
+- `returnType` = completion value. Optional.
+
+---
+
+## 6. Embedded payload schemas
+
+Every `jsonSchema.*` leaf (`body`, `response`, `params`, `yield`, `req.query`,
+error `schema`, …) is a plain **JSON Schema (Draft-07)** object as produced by
+the server's schema layer (TypeBox → JSON Schema). Expect standard keywords:
+`type`, `properties`, `required`, `items`, `enum`, `const`, `format`, `oneOf`,
+nested objects/arrays, etc.
+
+**Render these with a generic JSON-Schema viewer.** Don't hard-code field lists.
+Useful libraries: `@apidevtools/json-schema-ref-parser` (deref `$ref` if any),
+or any JSON-Schema-to-table/form renderer. They are validation-grade schemas, so
+you can also drive a "try it" form or example generator from them.
+
+---
+
+## 7. Suggested rendering model
+
+1. **Header:** `basePath`, route count, kind breakdown.
+2. **Sidebar:** group routes by `scope` (join array scopes with `/`), then by
+   `kind`. Label each with `name` + method/path.
+3. **Route detail:**
+   - Title: `name`; badge: `kind`; method(s); display path (`fullPath` ?? `path`).
+   - For `rpc`/`stream`: also show `version`.
+   - **Request** section from `body`/`params`/`req.*`.
+   - **Response** section from `response`/`res.*`; for streams, a **Stream**
+     section from `yield`/`yieldType` (+ `returnType`).
+   - **Errors** section: resolve each `errors[]` name against the catalog and
+     show status + description + body schema.
+4. **Errors page:** full `errors[]` catalog.
+5. **Headers page:** `headers[]` table.
+
+---
+
+## 8. Defensive checklist for the GUI
+
+- Validate `routes` is an array before anything else; otherwise it's not an envelope.
+- Switch on `kind`; render unknown `kind` values generically (future-proofing).
+- Treat HTTP methods case-insensitively (canonical output is lowercase, but
+  normalize anyway).
+- Tolerate empty/absent `headers`, `errors`, `jsonSchema`, `req`, `res`.
+- Tolerate extra/unknown properties at every level.
+- Read `specVersion` first (default 1 if absent) and branch parsing on it; warn on unknown-higher.
+- Don't expect a per-route `description`. `generatorVersion` is display-only, never a parse signal.
+- Prefer `fullPath` over `path` for `api`/`http-stream` display.
+- Unwrap the SSE envelope for `stream` `yieldType.data` when showing "event payload".

package/docs/doc-envelope-v1.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ts-procedures.dev/schemas/doc-envelope-v1.schema.json",
+  "title": "ts-procedures DocEnvelope (specVersion 1)",
+  "description": "The JSON document a ts-procedures server exposes (via builder.toDocEnvelope() / DocRegistry.toJSON()). Describes every procedure/route the server serves, the global error catalog, and global headers. Payload schemas embedded under each route's `jsonSchema` are arbitrary JSON Schema (Draft-07) objects and are intentionally left unconstrained here.",
+  "type": "object",
+  "required": ["basePath", "headers", "errors", "routes"],
+  "properties": {
+    "specVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Wire-format version of the envelope. A small monotonic integer, bumped ONLY when the envelope shape changes — not on every package release. Branch on this to pick a parser. ABSENT means treat as 1 (envelopes predating this field). Emitted by ts-procedures servers; optional here so older/hand-built documents still validate."
+    },
+    "generatorVersion": {
+      "type": "string",
+      "description": "ts-procedures package version that produced the envelope, e.g. \"10.0.0\". Informational only (telemetry/debugging) — do NOT use it for parse-compatibility decisions; use specVersion."
+    },
+    "basePath": {
+      "type": "string",
+      "description": "Path prefix shared by all routes, e.g. \"/api\". May be the empty string."
+    },
+    "headers": {
+      "type": "array",
+      "description": "Global HTTP headers documented for the whole API.",
+      "items": { "$ref": "#/definitions/HeaderDoc" }
+    },
+    "errors": {
+      "type": "array",
+      "description": "Catalog of every error the API may return (framework defaults + user-defined taxonomy). Routes reference these by name via their `errors` array.",
+      "items": { "$ref": "#/definitions/ErrorDoc" }
+    },
+    "routes": {
+      "type": "array",
+      "description": "All procedures/routes. Discriminated union on `kind`.",
+      "items": { "$ref": "#/definitions/AnyRouteDoc" }
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "JsonSchema": {
+      "description": "An embedded JSON Schema (Draft-07) object describing a payload. Left unconstrained on purpose — render it generically.",
+      "type": "object",
+      "additionalProperties": true
+    },
+    "HeaderDoc": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "required": { "type": "boolean" },
+        "example": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "ErrorDoc": {
+      "type": "object",
+      "required": ["name", "statusCode", "description"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique error name. Routes link to it via their `errors` array."
+        },
+        "statusCode": {
+          "type": "integer",
+          "description": "HTTP status code returned for this error.",
+          "minimum": 100,
+          "maximum": 599
+        },
+        "description": { "type": "string" },
+        "schema": {
+          "$ref": "#/definitions/JsonSchema",
+          "description": "JSON Schema of the error response body. Optional."
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "AnyRouteDoc": {
+      "oneOf": [
+        { "$ref": "#/definitions/RPCRouteDoc" },
+        { "$ref": "#/definitions/StreamRouteDoc" },
+        { "$ref": "#/definitions/APIRouteDoc" },
+        { "$ref": "#/definitions/HttpStreamRouteDoc" }
+      ]
+    },
+
+    "HttpMethod": {
+      "description": "HTTP method. Canonical wire form is lowercase; treat case-insensitively when rendering.",
+      "type": "string",
+      "enum": ["get", "post", "put", "delete", "patch", "head", "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"]
+    },
+
+    "StreamMode": {
+      "type": "string",
+      "enum": ["sse", "text"],
+      "description": "Stream transport. `sse` = Server-Sent Events; `text` = raw text chunks."
+    },
+
+    "Scope": {
+      "description": "Logical grouping. A single segment or an array of segments.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    },
+
+    "RPCRouteDoc": {
+      "title": "RPC route (kind = rpc)",
+      "description": "JSON-RPC-style procedure. Always POST. Path embeds scope + version.",
+      "type": "object",
+      "required": ["kind", "name", "path", "method", "scope", "version", "jsonSchema"],
+      "properties": {
+        "kind": { "const": "rpc" },
+        "name": { "type": "string" },
+        "path": { "type": "string", "description": "Full path incl. basePath + version, e.g. /api/users/get-user/1" },
+        "method": { "const": "post" },
+        "scope": { "$ref": "#/definitions/Scope" },
+        "version": { "type": "number" },
+        "errors": { "type": "array", "items": { "type": "string" } },
+        "jsonSchema": {
+          "type": "object",
+          "properties": {
+            "body": { "$ref": "#/definitions/JsonSchema", "description": "Request body schema (validated)." },
+            "response": { "$ref": "#/definitions/JsonSchema", "description": "Response body schema (doc only)." }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "StreamRouteDoc": {
+      "title": "RPC stream route (kind = stream)",
+      "description": "Streaming RPC procedure. Served over both POST and GET. Path embeds scope + version.",
+      "type": "object",
+      "required": ["kind", "name", "path", "methods", "streamMode", "scope", "version", "jsonSchema"],
+      "properties": {
+        "kind": { "const": "stream" },
+        "name": { "type": "string" },
+        "path": { "type": "string" },
+        "methods": {
+          "type": "array",
+          "description": "Allowed methods, conventionally [\"post\", \"get\"].",
+          "items": { "type": "string", "enum": ["get", "post"] }
+        },
+        "streamMode": { "$ref": "#/definitions/StreamMode" },
+        "scope": { "$ref": "#/definitions/Scope" },
+        "version": { "type": "number" },
+        "errors": { "type": "array", "items": { "type": "string" }, "description": "Pre-stream errors only." },
+        "jsonSchema": {
+          "type": "object",
+          "properties": {
+            "params": { "$ref": "#/definitions/JsonSchema", "description": "Query params (GET) or body (POST)." },
+            "yieldType": {
+              "$ref": "#/definitions/JsonSchema",
+              "description": "Schema for each streamed value. In `sse` mode this is the SSE envelope { data, event, id, retry } whose `data` holds the user's yield schema; in `text` mode it is the raw yield schema."
+            },
+            "returnType": { "$ref": "#/definitions/JsonSchema", "description": "Final return value schema." }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "APIRouteDoc": {
+      "title": "REST route (kind = api)",
+      "description": "REST-style HTTP endpoint with explicit method + path.",
+      "type": "object",
+      "required": ["kind", "name", "method", "fullPath", "jsonSchema"],
+      "properties": {
+        "kind": { "const": "api" },
+        "name": { "type": "string" },
+        "scope": { "type": "string" },
+        "path": { "type": "string", "description": "Path as registered (may include :params), e.g. /users/:id. May be omitted in some envelopes; prefer fullPath." },
+        "method": { "$ref": "#/definitions/HttpMethod" },
+        "fullPath": { "type": "string", "description": "Resolved path incl. basePath prefix, e.g. /api/users/:id." },
+        "successStatus": { "type": "integer", "description": "Status on success. Defaults: POST→201, DELETE→204, else 200." },
+        "errors": { "type": "array", "items": { "type": "string" } },
+        "jsonSchema": {
+          "type": "object",
+          "properties": {
+            "req": {
+              "type": "object",
+              "properties": {
+                "pathParams": { "$ref": "#/definitions/JsonSchema" },
+                "query": { "$ref": "#/definitions/JsonSchema" },
+                "body": { "$ref": "#/definitions/JsonSchema" },
+                "headers": { "$ref": "#/definitions/JsonSchema" }
+              },
+              "additionalProperties": true
+            },
+            "res": {
+              "type": "object",
+              "properties": {
+                "body": { "$ref": "#/definitions/JsonSchema" },
+                "headers": { "$ref": "#/definitions/JsonSchema" }
+              },
+              "additionalProperties": true
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "HttpStreamRouteDoc": {
+      "title": "REST stream route (kind = http-stream)",
+      "description": "REST-style streaming endpoint. Response has no single body; values arrive via `yield`. Currently always SSE.",
+      "type": "object",
+      "required": ["kind", "name", "method", "fullPath", "streamMode", "jsonSchema"],
+      "properties": {
+        "kind": { "const": "http-stream" },
+        "name": { "type": "string" },
+        "scope": { "type": "string" },
+        "path": { "type": "string" },
+        "method": { "$ref": "#/definitions/HttpMethod" },
+        "fullPath": { "type": "string" },
+        "streamMode": { "$ref": "#/definitions/StreamMode" },
+        "errors": { "type": "array", "items": { "type": "string" } },
+        "jsonSchema": {
+          "type": "object",
+          "properties": {
+            "req": {
+              "type": "object",
+              "properties": {
+                "pathParams": { "$ref": "#/definitions/JsonSchema" },
+                "query": { "$ref": "#/definitions/JsonSchema" },
+                "body": { "$ref": "#/definitions/JsonSchema" },
+                "headers": { "$ref": "#/definitions/JsonSchema" }
+              },
+              "additionalProperties": true
+            },
+            "res": {
+              "type": "object",
+              "description": "Response headers only — streaming responses have no single body.",
+              "properties": {
+                "headers": { "$ref": "#/definitions/JsonSchema" }
+              },
+              "additionalProperties": true
+            },
+            "yield": { "$ref": "#/definitions/JsonSchema", "description": "Schema for each streamed value. NOT wrapped in an SSE envelope (unlike kind=stream)." },
+            "returnType": { "$ref": "#/definitions/JsonSchema", "description": "Final return value schema." }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/docs/http-integrations.md

@@ -311,7 +311,33 @@ const docs = new DocRegistry({ errors: appErrors, basePath: '/api' })
 
 `http-stream` route docs include the route's `yield` and `res.headers` schemas. (Through v8, live envelopes silently dropped these for `http-stream` routes, so generated clients lost those types unless the envelope was hand-authored; v9 fixed this.)
 
-The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
+### Envelope versioning
+
+Every envelope carries two top-level metadata fields so downstream consumers (docs viewers, codegen, dashboards) can reason about format compatibility:
+
+```jsonc
+{
+  "specVersion": 1,             // wire-format version of the envelope itself
+  "generatorVersion": "10.0.0", // ts-procedures package version that produced it
+  "basePath": "/api",
+  "headers": [],
+  "errors": [ /* ... */ ],
+  "routes": [ /* ... */ ]
+}
+```
+
+- **`specVersion`** is a small monotonic integer, bumped **only** when the envelope shape changes in a way parsers must react to — never on ordinary package releases. Branch on it. An envelope with no `specVersion` predates the field and must be treated as `1`. The current value is exported as `DOC_ENVELOPE_SPEC_VERSION` from `ts-procedures` and `ts-procedures/server`.
+- **`generatorVersion`** is the producing package version (`DOC_ENVELOPE_GENERATOR_VERSION`, exported from `ts-procedures/server`). It is informational only — for telemetry and "which release served this?" — and must **not** drive parse-compatibility decisions, since it churns on every release regardless of the envelope format.
+
+If you'd rather not advertise the exact package version on a public docs endpoint, strip it with the `transform` hook:
+
+```typescript
+app.get('/docs', (c) => c.json(
+  builder.toDocEnvelope({ transform: ({ generatorVersion, ...env }) => env }),
+))
+```
+
+The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md). Building a third-party docs viewer or other tool that consumes the served envelope? The full wire contract — every field, per-kind shapes, and a validatable JSON Schema — is in [DocEnvelope Spec](./doc-envelope-spec-v1.md) (`doc-envelope-v1.schema.json`).
 
 ## Type Exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "10.0.0",
+  "version": "10.1.1",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

package/src/adapters/hono/envelope-parity.test.ts

@@ -3,8 +3,10 @@ import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { Type } from 'typebox'
+import pkg from '../../../package.json' with { type: 'json' }
 import { Procedures } from '../../core/procedures.js'
 import { HonoAppBuilder, defineErrorTaxonomy } from './index.js'
+import { DOC_ENVELOPE_SPEC_VERSION } from '../../server/spec-version.js'
 import type { RPCConfig } from '../../server/types.js'
 
 /**
@@ -16,12 +18,15 @@ import type { RPCConfig } from '../../server/types.js'
  * The envelope is codegen's input; if this test fails, generated client output
  * WILL drift.
  *
- * ONE documented deviation from the raw v8 capture: v8's CreateHttpStream
- * dropped the `yield` schema (and `res.headers`) from http-stream route docs —
- * the registration stored `yieldType` while the doc builder read `yield`. v9
- * fixes that, so the fixture's TailUser route was patched to include the
- * `yield` schema the builder now (correctly) emits. Everything else is the
- * untouched v8 capture.
+ * TWO documented deviations from the raw v8 capture:
+ *   1. v8's CreateHttpStream dropped the `yield` schema (and `res.headers`) from
+ *      http-stream route docs — the registration stored `yieldType` while the
+ *      doc builder read `yield`. v9 fixes that, so the fixture's TailUser route
+ *      was patched to include the `yield` schema the builder now emits.
+ *   2. v9 adds envelope-level `specVersion`/`generatorVersion` metadata that v8
+ *      never emitted. These are asserted explicitly below, then stripped before
+ *      the deep-equal so the rest stays byte-for-byte with the v8 capture.
+ * Everything else is the untouched v8 capture.
  */
 class TeapotError extends Error {}
 
@@ -121,6 +126,13 @@ describe('DocEnvelope parity with v8.6.0', () => {
     const expected = JSON.parse(await readFile(fixturePath, 'utf-8'))
     const actual = JSON.parse(JSON.stringify(builder.toDocEnvelope()))
 
+    // Deviation #2: assert the new v9 envelope metadata, then strip it so the
+    // remaining shape matches the untouched v8 capture.
+    expect(actual.specVersion).toBe(DOC_ENVELOPE_SPEC_VERSION)
+    expect(actual.generatorVersion).toBe(pkg.version)
+    delete actual.specVersion
+    delete actual.generatorVersion
+
     expect(actual).toEqual(expected)
   })
 })

package/src/codegen/constants.ts

@@ -1,4 +1,4 @@
-import pkg from '../../package.json' with { type: 'json' }
+import { PACKAGE_VERSION } from '../version.js'
 
 /**
  * Stable, version-agnostic token embedded in every generated file (across all
@@ -7,4 +7,4 @@ import pkg from '../../package.json' with { type: 'json' }
  * the package version (an orphan left by an older release must still match).
  */
 export const CODEGEN_SIGNATURE = 'ts-procedures-codegen'
-export const CODEGEN_HEADER = `// Auto-generated by ${CODEGEN_SIGNATURE} (v${pkg.version}) — do not edit`
+export const CODEGEN_HEADER = `// Auto-generated by ${CODEGEN_SIGNATURE} (v${PACKAGE_VERSION}) — do not edit`

package/src/exports.ts

@@ -56,5 +56,9 @@ export type { Infer, TSchemaLib, TJSONSchema, Prettify } from './schema/json-sch
 
 // Doc envelope — offline codegen input
 export { writeDocEnvelope } from './server/doc-envelope.js'
+// `generatorVersion` metadata lives on `ts-procedures/server`
+// (DOC_ENVELOPE_GENERATOR_VERSION) — it's niche telemetry. The spec version is
+// the one consumers branch on, so it gets the prominent top-level export.
+export { DOC_ENVELOPE_SPEC_VERSION } from './server/spec-version.js'
 export type { DocEnvelopeSource } from './server/doc-envelope.js'
 export type { DocEnvelope } from './server/types.js'