ts-procedures 10.1.1 → 10.2.0

package/build/server/spec-version.d.ts

@@ -1,24 +0,0 @@
-/**
- * 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 declare 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 declare const DOC_ENVELOPE_GENERATOR_VERSION: string;

package/build/server/spec-version.js

@@ -1,26 +0,0 @@
-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 = PACKAGE_VERSION;
-//# sourceMappingURL=spec-version.js.map

package/build/server/spec-version.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"spec-version.js","sourceRoot":"","sources":["../../src/server/spec-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAW,eAAe,CAAA"}

package/build/version.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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 declare const PACKAGE_VERSION: string;

package/build/version.js

@@ -1,11 +0,0 @@
-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 = pkg.version;
-//# sourceMappingURL=version.js.map

package/build/version.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAW,GAAG,CAAC,OAAO,CAAA"}

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

@@ -1,296 +0,0 @@
-# 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

@@ -1,253 +0,0 @@
-{
-  "$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/src/server/spec-version.ts

@@ -1,27 +0,0 @@
-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