ts-procedures 8.5.0 → 9.0.0

package/docs/specs/2026-06-09-v9-rewrite-design.md

@@ -0,0 +1,221 @@
+# ts-procedures v9 — Ground-Up Rewrite Design
+
+**Date:** 2026-06-09
+**Status:** Approved for implementation (autonomous /goal directive; final review with user at the end)
+**Location:** `v9/` — a self-contained package directory inside the repo, fully separate from the root v8 project.
+
+## 1. Goal
+
+Build the next major version (9.0.0) of `ts-procedures` as a brand-new package in `v9/`, with its own
+`package.json`, free to break any API — **except generated codegen output, which must remain exactly what
+v8.6.0 emits today** (TS, Kotlin, Swift; all mode combinations). Downstream apps depend on that polished output.
+
+Quality bar: most readable, well-structured, best-DX, extendable, configurable, pluggable version of the
+library possible.
+
+## 2. The one hard constraint, made executable
+
+"Codegen output that currently exists" becomes a byte-level golden contract:
+
+1. **Capture baselines from v8 first.** A capture script runs the *current root build's* codegen
+   (`../build/codegen`) against fixture envelopes and writes every generated file to
+   `v9/src/codegen/__goldens__/<case>/`.
+2. **Golden matrix** (each case = full output dir):
+   - `ts-default` — namespace mode, selfContained, shareModels, jsdoc (all defaults)
+   - `ts-flat` — `namespaceTypes: false`
+   - `ts-external-runtime` — `selfContained: false`
+   - `ts-no-share-models` — `shareModels: false`
+   - `ts-shared-models-module` — `sharedModelsModule` convention path
+   - `kotlin-default` — kotlinx serializer
+   - `swift-default` — codable serializer
+3. **Fixture envelopes:** the existing `users-envelope.json` plus a richer `models-envelope.json`
+   (adds `$id`-bearing shared models across scopes, route-level `errors`, http-stream routes) so the
+   shareModels/`_models.ts` paths are pinned too.
+4. **Golden test harness** in v9 compares v9 output byte-for-byte against the captured baselines, splicing
+   two placeholders: the envelope hash comment (already supported by v8's golden helper) and the package
+   version in `CODEGEN_HEADER` (v9 emits `9.x`; everything else must match exactly).
+5. These tests are written **before** any v9 codegen code and stay red until the port is faithful.
+
+Two corollaries that fall out of the constraint:
+
+- **Bundled client runtime is content-frozen.** Self-contained mode concatenates `src/client/*.ts`
+  verbatim (imports stripped) into `_client.ts`/`_types.ts`. Therefore v9's `src/client/` keeps the same
+  ten files with byte-identical content. Client improvements are out of scope for 9.0 and gated on a
+  future bundler change.
+- **DocEnvelope JSON shape is frozen.** It is codegen's input. Server-side APIs may change freely as long
+  as `toDocEnvelope()` emits the same shapes (`kind` discriminants, `jsonSchema` channel layout, SSE
+  envelope wrapping, `fullPath`, `errors: string[]`, ErrorDoc/HeaderDoc).
+
+## 3. What changes vs. what is preserved
+
+| Area | v9 disposition |
+|---|---|
+| Codegen emitted output | **Frozen** (golden-verified) |
+| Codegen internals | Restructured: `emit-scope.ts` (1049 LOC) split into per-kind emitters + shared formatting modules; CLI parsing derived from `FLAG_SPECS` instead of a parallel hand-written switch |
+| Client runtime (`src/client/`) | **Frozen content** (bundling), ported verbatim |
+| DocEnvelope shape | **Frozen** |
+| Core factory / Create* API | Redesigned for DX (see §5) |
+| Schema layer | Pluggable adapters; **Suretype dropped**; AJV configurable |
+| HTTP server layer | Split into transport-agnostic `server/` + thin framework adapters (`hono/`, `astro/`) |
+| Error taxonomy | Kept (it's good); relocated to `server/errors/`; same semantics |
+| Subpath exports | Same names kept (`.`/`./hono`/`./astro`/`./http`/`./http-docs`/`./http-errors`/`./client`/`./codegen`), plus new `./server` |
+| agent_config | Out of scope for the v9 directory (release-time copy; root owns it today) |
+
+## 4. Package layout
+
+```
+v9/
+├── package.json            # name: ts-procedures, version: 9.0.0, type: module
+├── tsconfig.json           # ES2024, NodeNext, strict — mirrors root
+├── vitest.config.ts
+├── eslint.config.js
+├── docs/
+│   └── specs/2026-06-09-v9-rewrite-design.md   (this file)
+├── tools/
+│   └── capture-goldens.mjs # runs root v8 build's codegen → __goldens__
+└── src/
+    ├── exports.ts          # root barrel
+    ├── core/               # framework-agnostic procedure definitions
+    │   ├── procedures.ts   # Procedures() factory + registry
+    │   ├── create.ts / create-stream.ts / create-http.ts / create-http-stream.ts
+    │   ├── context.ts      # ctx.error(), signal contracts
+    │   ├── errors.ts       # ProcedureError family (4 classes, shared base)
+    │   ├── definition-site.ts  # stack-capture (was stack-utils.ts)
+    │   └── types.ts
+    ├── schema/
+    │   ├── adapter.ts      # SchemaAdapter interface (extract + infer hooks)
+    │   ├── typebox.ts      # built-in TypeBox adapter (auto-detected default)
+    │   ├── compile.ts      # AJV compilation, factory-configurable instance
+    │   └── compute-schema.ts
+    ├── server/             # transport-agnostic HTTP machinery (NEW seam)
+    │   ├── types.ts        # DocEnvelope, route docs (frozen shapes)
+    │   ├── docs/           # buildRpc/Api/Stream/HttpStream route docs
+    │   ├── doc-registry.ts
+    │   ├── doc-envelope.ts # writeDocEnvelope
+    │   ├── errors/
+    │   │   ├── taxonomy.ts # defineErrorTaxonomy, defaults, topo sort
+    │   │   └── dispatch.ts # pre-stream / mid-stream dispatch
+    │   ├── request/
+    │   │   ├── params.ts   # extractParams (pathParams/query/body/headers)
+    │   │   └── query.ts    # parseQueryNative + QueryParser type
+    │   ├── sse.ts          # sse() metadata, SSE event sequencing helper
+    │   └── paths.ts        # makeRoutePath, resolveFullPath
+    ├── adapters/
+    │   ├── hono/           # thin HonoAppBuilder over server/*
+    │   └── astro/          # port of the astro handler
+    ├── client/             # FROZEN content (ten files, verbatim from v8)
+    └── codegen/
+        ├── pipeline.ts, resolve-envelope.ts, group-routes.ts, ...
+        ├── emit/           # was emit-scope.ts — split:
+        │   ├── scope-file.ts        # orchestration (namespace/flat assembly)
+        │   ├── rpc-route.ts / api-route.ts / stream-route.ts / http-stream-route.ts
+        │   ├── format-types.ts      # formatTypes/formatSubNamespace/rename
+        │   └── declarations.ts      # DeclarationCollector
+        ├── targets/{_shared,ts,kotlin,swift}/
+        ├── bin/{cli.ts,flag-specs.ts}
+        ├── __fixtures__/   # users-envelope.json + models-envelope.json
+        └── __goldens__/    # captured v8 output (the contract)
+```
+
+Build = plain `tsc` to `build/`, ESM-only — same as v8 (it works and keeps publishing simple).
+Root `vitest.config.ts` excludes `v9/`; v9 has its own config (complete separation).
+
+## 5. Core API design
+
+The four kinds stay (`rpc`, `rpc-stream`, `http`, `http-stream`) and the dual-return shape stays — both
+are proven DX:
+
+```ts
+const { GetUser, procedure, info } = Create('GetUser', { schema: { params, returnType } }, handler)
+```
+
+Changes:
+
+1. **Single options bag for the factory** with named sub-configs replacing scattered flags:
+   ```ts
+   const { Create, CreateStream, CreateHttp, CreateHttpStream, getProcedures } =
+     Procedures<Ctx, Ext>({
+       onCreate?: (registration) => void,
+       validation?: false | { ajv?: AjvLike | AjvOptions },   // replaces noRuntimeValidation: true
+       schema?: { adapter?: SchemaAdapter },                  // pluggable; TypeBox auto-detected default
+       http?: { pathPrefix?: string, scope?: string },        // factory-level defaults for CreateHttp*
+     })
+   ```
+   `validation: false` reads better than `noRuntimeValidation: true`; AJV options/instance become
+   injectable instead of a hardcoded module singleton (default stays `allErrors + coerceTypes +
+   removeAdditional` for behavioral parity).
+2. **Factory-level HTTP defaults** (`http.pathPrefix`, `http.scope`) merge under each `CreateHttp` config —
+   addresses the documented per-route boilerplate pain without changing envelope output shape.
+3. **Error classes:** keep the four (`ProcedureError`, `ProcedureValidationError`,
+   `ProcedureYieldValidationError`, `ProcedureRegistrationError`) because taxonomy dispatch and docs key
+   off `instanceof` and class names; unify internals on one base with a `kind` field, keep definition-site
+   stack enrichment (genuinely good v8 feature).
+4. **Schema layer:** `SchemaAdapter = { detect(schema): boolean; toJsonSchema(schema): TJSONSchema }`.
+   TypeBox adapter ships built-in and is the default; Suretype is removed (deprecated since v8). The AJV
+   compile step lives in `schema/compile.ts` behind a small `Validator` type so a future non-AJV engine is
+   a config swap, not a rewrite.
+5. **Context contract unchanged** (`ctx.error()`, `ctx.signal?` on rpc/http, guaranteed `ctx.signal` on
+   streams, `isPrevalidated` escape hatch kept for builders).
+
+## 6. Server layer design
+
+The v8 hono directory mixes three concerns: framework binding, HTTP semantics, and doc generation. v9
+separates them:
+
+- **`server/`** is pure: no Hono imports. It owns param extraction, query parsing, success-status
+  defaults, SSE event sequencing (auto-incrementing ids, `event: 'return'` envelope, `sse()` metadata via
+  WeakMap), error taxonomy + pre/mid-stream dispatch, route-doc builders, DocRegistry, and path resolution.
+  This kills the v8 duplication (query/param extraction copy-pasted between http.ts and http-stream.ts;
+  near-identical SSE loops in stream.ts and http-stream.ts) once, in one place.
+- **`adapters/hono/`** keeps the v8 `HonoAppBuilder` surface users like — chainable `register()`,
+  stratified config (`rpc.*`, `api.*`, `stream.*`, cross-cutting `errors`/`unknownError`/`onError`/
+  `onRequestError`/`onRequestStart/End`), lazy `docs`, `build()`, `toDocEnvelope()` — but each handler is
+  ~20 lines of Hono-specific glue (read request, call server/* helpers, write response). Writing a
+  Fastify/Express adapter becomes a contained exercise against documented seams rather than a fork.
+- **Envelope parity test:** build the same factories through the v9 hono builder and assert deep-equality
+  of `toDocEnvelope()` against a captured v8 envelope for the same procedure set.
+
+## 7. Codegen design
+
+Port with internal restructuring, never output restructuring:
+
+1. Goldens first (see §2) — red until faithful.
+2. Modules port nearly as-is where already clean (`pipeline.ts`, `group-routes.ts`, `collect-models.ts`,
+   `model-refs.ts`, `emit-models.ts`, `emit-errors.ts`, `emit-index.ts`, `targets/*`).
+3. `emit-scope.ts` is split into `emit/` per-kind modules (§4 layout). Every emitted string literal moves
+   verbatim; only file boundaries and shared helpers change.
+4. `emit-client-runtime.ts` / `emit-client-types.ts` read v9's `src/client/*.ts` — identical content by
+   the freeze in §2 — so `_client.ts`/`_types.ts` match.
+5. CLI: `parseArgs` is generated from `FLAG_SPECS` (single source of truth; v8 had a hand-written switch
+   plus a parallel spec table that could drift). Flags, defaults, help text, error messages, and
+   did-you-mean behavior remain identical and are covered by ported CLI tests.
+6. `generateClient` options, config-file loading, watch mode, orphan pruning (`CODEGEN_SIGNATURE`
+   version-agnostic) all keep v8 semantics.
+
+## 8. Testing strategy
+
+- **Goldens** (§2) are the spine — they encode the only hard requirement.
+- **Envelope parity** test for the hono builder (§6).
+- **Ported unit tests:** v8's co-located tests move with each module (adapted imports/APIs). Target: the
+  full behavioral surface of core/schema/server/client/codegen covered; client tests port verbatim since
+  the runtime is verbatim.
+- **New tests** for new seams: SchemaAdapter plug-in, factory `validation`/`http` defaults, server/*
+  helpers in isolation.
+- TDD discipline for all newly designed code (core/schema/server); port-then-verify for frozen code.
+
+## 9. Out of scope for 9.0.0
+
+- Client runtime improvements (frozen by the bundling contract; revisit with an AST-based bundler in 9.x).
+- New codegen targets, new emit options.
+- agent_config refresh, README/marketing docs rewrite (a migration guide `docs/migration-v8-to-v9.md` IS
+  in scope).
+- Suretype support (removed), Express builder (the v9 seam makes it easy later, not built now).
+
+## 10. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Hidden output drift in untested codegen paths | Two fixture envelopes × 7-case matrix; richer than v8's own coverage; e2e content tests also ported |
+| Client verbatim port silently diverges | A test hashes each of the ten client files against recorded v8 hashes |
+| Envelope drift from redesigned server layer | Deep-equality envelope parity test |
+| ajsc version behavior | Same dependency pin (`^7.3.0`), same dynamic-import pattern |

package/docs/streaming.md

@@ -109,6 +109,18 @@ for await (const item of CancellableStream({}, {})) {
 
 For the built-in Hono streaming integration, see [HTTP Integrations](./http-integrations.md). `HonoAppBuilder` dispatches `CreateStream` and `CreateHttpStream` procedures as SSE or text streams from the same `register()` call as your RPC and REST routes.
 
+Wrap a yield with the `sse()` helper to attach SSE metadata (`event:`, `id:`, `retry:` fields). The value is returned unchanged — metadata rides in a WeakMap, never on the payload:
+
+```typescript
+import { sse } from 'ts-procedures/hono'
+
+async function* (ctx, params) {
+  yield sse({ progress: 0.5 }, { event: 'progress', id: 'p-1' })
+}
+```
+
+SSE wire behavior is identical for `rpc-stream` (`CreateStream`) and `http-stream` (`CreateHttpStream`) routes — both are served by the same event sequencer. `sse()` metadata is honored on both kinds, and a `null` yield serializes as empty SSE data on both. (Through v8, `http-stream` routes ignored `sse()` metadata and wrote the string `null` for null yields; v9 normalized this.)
+
 ## Stream Errors
 
 Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)).

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "ts-procedures",
-  "version": "8.5.0",
+  "version": "9.0.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",
   "type": "module",
   "sideEffects": false,
   "bin": {
-    "ts-procedures-setup": "./agent_config/bin/setup.mjs",
-    "ts-procedures-codegen": "./build/codegen/bin/cli.js"
+    "ts-procedures-setup": "agent_config/bin/setup.mjs",
+    "ts-procedures-codegen": "build/codegen/bin/cli.js"
   },
   "scripts": {
     "build": "tsc",
     "lint": "npx eslint src/ --quiet",
-    "check-docs": "bash scripts/check-docs-consistency.sh",
-    "prepublishOnly": "npm run lint && npm run build && npm run check-docs",
-    "postinstall": "node ./agent_config/bin/postinstall.mjs",
-    "test": "vitest run"
+    "test": "vitest run",
+    "check": "tsc --noEmit && vitest run && npm run lint",
+    "postinstall": "node ./agent_config/bin/postinstall.mjs"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -25,23 +24,27 @@
       "import": "./build/exports.js"
     },
     "./astro": {
-      "types": "./build/implementations/http/astro/index.d.ts",
-      "import": "./build/implementations/http/astro/index.js"
+      "types": "./build/adapters/astro/index.d.ts",
+      "import": "./build/adapters/astro/index.js"
     },
     "./http": {
-      "types": "./build/implementations/types.d.ts"
+      "types": "./build/server/types.d.ts"
     },
     "./hono": {
-      "types": "./build/implementations/http/hono/index.d.ts",
-      "import": "./build/implementations/http/hono/index.js"
+      "types": "./build/adapters/hono/index.d.ts",
+      "import": "./build/adapters/hono/index.js"
+    },
+    "./server": {
+      "types": "./build/server/index.d.ts",
+      "import": "./build/server/index.js"
     },
     "./http-docs": {
-      "types": "./build/implementations/http/doc-registry.d.ts",
-      "import": "./build/implementations/http/doc-registry.js"
+      "types": "./build/server/doc-registry.d.ts",
+      "import": "./build/server/doc-registry.js"
     },
     "./http-errors": {
-      "types": "./build/implementations/http/error-taxonomy.d.ts",
-      "import": "./build/implementations/http/error-taxonomy.js"
+      "types": "./build/server/errors/taxonomy.d.ts",
+      "import": "./build/server/errors/taxonomy.js"
     },
     "./client": {
       "types": "./build/client/index.d.ts",
@@ -55,38 +58,11 @@
   "author": "coryrobinson42@gmail.com",
   "license": "MIT",
   "files": [
-    "assets",
     "build",
     "docs",
     "agent_config",
     "src"
   ],
-  "keywords": [
-    "typescript",
-    "rpc",
-    "type-safe",
-    "validation",
-    "procedures",
-    "api",
-    "framework",
-    "hono",
-    "http",
-    "rest",
-    "schema",
-    "json-schema",
-    "typebox",
-    "ajv",
-    "schema-validation",
-    "type-inference",
-    "codegen",
-    "code-generation",
-    "client-generation",
-    "streaming",
-    "sse",
-    "server-sent-events",
-    "endpoint",
-    "trpc"
-  ],
   "optionalDependencies": {
     "ajsc": "^7.3.0",
     "astro": "6.x.x || 7.x.x",
@@ -96,18 +72,18 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "es-toolkit": "^1.44.0",
-    "suretype": "^3.3.1",
     "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",
-    "prettier": "^3.8.1",
-    "suretype": "^3.3.1",
-    "typebox": "^1.0.77",
+    "typescript": "^5.7.0",
     "typescript-eslint": "^8.53.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
     "vitest": "^4.0.18"
   }
 }

package/src/{implementations/http → adapters}/astro/index.test.ts

@@ -4,9 +4,9 @@ import { Type } from 'typebox'
 import { stripPrefix } from './rewrite-request.js'
 import { setAstroContext, getAstroContext } from './astro-context.js'
 import { createAstroHandler } from './create-handler.js'
-import { Procedures } from '../../../index.js'
+import { Procedures } from '../../core/procedures.js'
 import { HonoAppBuilder } from '../hono/index.js'
-import type { RPCConfig } from '../../types.js'
+import type { RPCConfig } from '../../server/types.js'
 
 // Minimal stand-in for Astro's APIContext for unit tests.
 function fakeApiContext(overrides: Record<string, unknown> = {}) {