ts-procedures 9.2.0 → 10.1.0

package/docs/doc-envelope.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://ts-procedures.dev/schemas/doc-envelope.schema.json",
+  "title": "ts-procedures DocEnvelope",
+  "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.md) (`doc-envelope.schema.json`).
 
 ## Type Exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "9.2.0",
+  "version": "10.1.0",
   "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",
@@ -76,15 +76,15 @@
     "typebox": "^1.0.30"
   },
   "devDependencies": {
-    "@eslint/js": "^9.17.0",
-    "astro": "^6.3.1",
-    "eslint": "^9.17.0",
-    "globals": "^15.0.0",
-    "hono": "^4.7.4",
-    "typescript": "^5.7.0",
-    "typescript-eslint": "^8.53.0",
+    "@eslint/js": "^10.0.1",
     "@typescript-eslint/eslint-plugin": "^8.53.0",
     "@typescript-eslint/parser": "^8.53.0",
+    "astro": "^7.0.2",
+    "eslint": "^10.5.0",
+    "globals": "^17.7.0",
+    "hono": "^4.7.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.53.0",
     "vitest": "^4.0.18"
   }
 }

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/bin/cli.ts

@@ -79,7 +79,7 @@ export async function loadConfigFile(configPath?: string): Promise<CodegenConfig
   } catch (err) {
     if (configPath !== undefined) {
       // Explicit path — always throw
-      throw new Error(`[ts-procedures-codegen] Failed to load config from ${filePath}: ${err instanceof Error ? err.message : err}`)
+      throw new Error(`[ts-procedures-codegen] Failed to load config from ${filePath}: ${err instanceof Error ? err.message : err}`, { cause: err })
     }
     // Default path — silently ignore if not found
     return undefined

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/codegen/emit/api-route.ts

@@ -62,7 +62,7 @@ export async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext
 
   const declarations: string[] = []
   let paramsTypeName = 'void'
-  let returnTypeName = 'void'
+  let returnTypeName: string
 
   // Track reserved names across all sub-namespaces. Model names are reserved
   // so an ajsc-extracted sub-type can't silently merge with a referenced model.

package/src/codegen/emit/scope-file.ts

@@ -132,7 +132,8 @@ export async function emitScopeFile(
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       throw new Error(
-        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`
+        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`,
+        { cause: err }
       )
     }
 

package/src/codegen/emit-errors.integration.test.ts

@@ -91,7 +91,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
       }
 
       // Dynamic import of the compiled output.
@@ -164,7 +164,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
       }
 
       const errorsUrl = `file://${join(outDir, 'out', '_errors.js')}`

package/src/codegen/resolve-envelope.ts

@@ -21,7 +21,7 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
       response = await fetch(input.url)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
-      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`)
+      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`, { cause: err })
     }
     if (!response.ok) {
       throw new Error(`[ts-procedures-codegen] ${input.url} returned HTTP ${response.status} ${response.statusText}`)

package/src/codegen/test-helpers/run-tsc.ts

@@ -51,6 +51,7 @@ export function runTsc(args: {
     const combined = [stdout, stderr].filter(Boolean).join('\n').trim()
     throw new Error(
       `[runTsc] tsc failed for ${tsconfigPath}:\n${combined || (e.message ?? '(no output)')}`,
+      { cause: err },
     )
   }
 }

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'

package/src/server/doc-registry.test.ts

@@ -5,7 +5,9 @@ import type {
   THttpStreamProcedureRegistration,
   TProcedureRegistration,
 } from '../core/types.js'
+import pkg from '../../package.json' with { type: 'json' }
 import { DocRegistry } from './doc-registry.js'
+import { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 import { defineErrorTaxonomy } from './errors/taxonomy.js'
 import { buildRpcRouteDoc } from './docs/rpc-doc.js'
 import { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
@@ -201,6 +203,38 @@ describe('DocRegistry', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // toJSON() spec metadata
+  // --------------------------------------------------------------------------
+  describe('toJSON() spec metadata', () => {
+    test('emits specVersion (the constant, a number) and generatorVersion (the package version)', () => {
+      const out = new DocRegistry().toJSON()
+      expect(out.specVersion).toBe(DOC_ENVELOPE_SPEC_VERSION)
+      expect(typeof out.specVersion).toBe('number')
+      expect(out.generatorVersion).toBe(pkg.version)
+      // the exported constant must track the real package version
+      expect(DOC_ENVELOPE_GENERATOR_VERSION).toBe(pkg.version)
+    })
+
+    test('metadata is present even on an otherwise-empty envelope', () => {
+      const out = new DocRegistry({ includeDefaults: false }).toJSON()
+      expect(out).toMatchObject({
+        specVersion: DOC_ENVELOPE_SPEC_VERSION,
+        generatorVersion: pkg.version,
+      })
+    })
+
+    test('transform receives the metadata on its envelope argument', () => {
+      const seen = new DocRegistry().toJSON({
+        transform: ({ specVersion, generatorVersion }) => ({ specVersion, generatorVersion }),
+      })
+      expect(seen).toEqual({
+        specVersion: DOC_ENVELOPE_SPEC_VERSION,
+        generatorVersion: pkg.version,
+      })
+    })
+  })
+
   // --------------------------------------------------------------------------
   // toJSON() filter
   // --------------------------------------------------------------------------

package/src/server/doc-registry.ts

@@ -13,6 +13,7 @@ import {
   taxonomyToErrorDocs,
   type ErrorTaxonomy,
 } from './errors/taxonomy.js'
+import { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 
 export type {
   AnyHttpRouteDoc,
@@ -112,6 +113,8 @@ export class DocRegistry {
     }
 
     const envelope: DocEnvelope = {
+      specVersion: DOC_ENVELOPE_SPEC_VERSION,
+      generatorVersion: DOC_ENVELOPE_GENERATOR_VERSION,
       basePath: this.basePath,
       headers: [...this.headers],
       errors: [...this.errors],

package/src/server/index.ts

@@ -25,5 +25,6 @@ export { buildStreamRouteDoc } from './docs/stream-doc.js'
 export { buildHttpRouteDoc } from './docs/http-doc.js'
 export { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
 export { DocRegistry } from './doc-registry.js'
+export { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 export { writeDocEnvelope } from './doc-envelope.js'
 export type { DocEnvelopeSource } from './doc-envelope.js'

package/src/server/spec-version.ts

@@ -0,0 +1,27 @@
+import { PACKAGE_VERSION } from '../version.js'
+
+/**
+ * Spec version of the {@link DocEnvelope} wire format.
+ *
+ * Bump this ONLY when the envelope shape changes in a way downstream parsers
+ * must react to — field renames, nesting changes, or semantic changes. Do NOT
+ * bump it on ordinary package releases (dependency upgrades, bug fixes, new
+ * optional fields that older parsers can safely ignore). It is decoupled from
+ * the npm package version on purpose, so consumers get a small monotonic
+ * integer to branch on instead of having to interpret semver.
+ *
+ * Consumer contract: an envelope with no `specVersion` field predates this
+ * field and MUST be treated as spec version 1.
+ */
+export const DOC_ENVELOPE_SPEC_VERSION = 1
+
+/**
+ * The ts-procedures package version that produced an envelope (e.g. `"10.0.0"`).
+ * Populates the envelope's `generatorVersion` field.
+ *
+ * Informational only — for telemetry, debugging, and "which release served
+ * this?" questions. Do NOT use it to decide parse compatibility; it churns on
+ * every release regardless of whether the envelope format changed. Use
+ * {@link DOC_ENVELOPE_SPEC_VERSION} for compatibility decisions.
+ */
+export const DOC_ENVELOPE_GENERATOR_VERSION: string = PACKAGE_VERSION

package/src/server/types.ts

@@ -250,6 +250,21 @@ export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {
 }
 
 export interface DocEnvelope {
+  /**
+   * Wire-format version of this envelope. Every envelope produced by
+   * `DocRegistry.toJSON()` / `builder.toDocEnvelope()` carries it. Downstream
+   * consumers branch on it to pick a parser; bumped only on envelope format
+   * changes, NOT on package releases. Optional on the type so hand-built
+   * envelopes and pre-existing documents remain valid — an absent value MUST be
+   * treated as spec version 1. See {@link DOC_ENVELOPE_SPEC_VERSION}.
+   */
+  specVersion?: number
+  /**
+   * ts-procedures package version that produced this envelope (e.g. `"10.0.0"`).
+   * Informational only — do not use for parse-compatibility decisions (use
+   * {@link specVersion} for that). See {@link DOC_ENVELOPE_GENERATOR_VERSION}.
+   */
+  generatorVersion?: string
   basePath: string
   headers: HeaderDoc[]
   errors: ErrorDoc[]

package/src/version.ts

@@ -0,0 +1,11 @@
+import pkg from '../package.json' with { type: 'json' }
+
+/**
+ * The ts-procedures package version (e.g. `"10.0.0"`), read from `package.json`.
+ *
+ * Single source of truth for "which version is this build?" — consumed by the
+ * codegen file header and the doc-envelope `generatorVersion`. Import this
+ * rather than re-importing `package.json`, so there's one place the version
+ * enters the source tree.
+ */
+export const PACKAGE_VERSION: string = pkg.version

package/build/errors.d.ts

@@ -1,33 +0,0 @@
-import { TSchemaValidationError } from './schema/parser.js';
-import { DefinitionInfo, DefinitionLocation } from './stack-utils.js';
-export declare class ProcedureError extends Error {
-    readonly procedureName: string;
-    readonly message: string;
-    readonly meta?: object | undefined;
-    cause?: unknown;
-    readonly definedAt?: DefinitionLocation;
-    readonly definitionStack?: string;
-    constructor(procedureName: string, message: string, meta?: object | undefined, definitionInfo?: DefinitionInfo);
-    /**
-     * Returns a formatted string showing where the procedure was defined.
-     */
-    getDefinitionLocation(): string | undefined;
-    /**
-     * Enhances the error stack with definition location information.
-     */
-    private enhanceStack;
-}
-export declare class ProcedureValidationError extends ProcedureError {
-    readonly procedureName: string;
-    readonly errors?: TSchemaValidationError[] | undefined;
-    constructor(procedureName: string, message: string, errors?: TSchemaValidationError[] | undefined, definitionInfo?: DefinitionInfo);
-}
-export declare class ProcedureRegistrationError extends ProcedureError {
-    readonly procedureName: string;
-    constructor(procedureName: string, message: string, definitionInfo?: DefinitionInfo);
-}
-export declare class ProcedureYieldValidationError extends ProcedureError {
-    readonly procedureName: string;
-    readonly errors?: TSchemaValidationError[] | undefined;
-    constructor(procedureName: string, message: string, errors?: TSchemaValidationError[] | undefined, definitionInfo?: DefinitionInfo);
-}