ts-procedures 8.6.0 → 9.1.0

package/docs/npm-workspaces-migration-plan.md

@@ -1,611 +0,0 @@
-# ts-procedures → npm workspaces monorepo migration plan
-
-> **⚠️ SUPERSEDED (2026-06-02) — NOT the current direction.**
-> The split was evaluated and **declined**; we stay single-package. See the
-> decision record: [`docs/decisions/2026-06-02-monorepo-split-evaluation.md`](decisions/2026-06-02-monorepo-split-evaluation.md).
-> This document is retained only as a starting point if the split is ever
-> revived for an independent-versioning or `@ts-procedures` branding reason.
-> Note two corrections the decision record carries: codegen→core must be a
-> **normal** dependency (its public API leaks `DocEnvelope`), and the wire
-> contract should be a named `core/contract` seam.
-
-Status: **READY — simplified design. All prior hard blockers resolved or designed out.**
-Target: split the single `ts-procedures@8.1.0` package into an npm-workspaces
-monorepo of **7** scoped packages under `@ts-procedures/*`, published fresh at
-`v1.0.0` in lockstep. **No meta/shim package** — `ts-procedures@8.1.0` is
-deprecated in place.
-
-This revision incorporates a line-by-line source verification (June 2026) and
-four maintainer decisions that deliberately favor maintainability and DX over
-cleverness:
-
-1. **No `@ts-procedures/http-protocol` package.** Wire-contract types live in
-   `@ts-procedures/core`; everyone `import type`s them. Verified: codegen's
-   dependency on those types is 100% type-only, so a separate runtime-free
-   package buys nothing. This dissolves two of the original "blockers."
-2. **No meta-package.** A `ts-procedures@9` re-export shim would carry zero real
-   changes. Skip it. Hard, honest import cutover instead.
-3. **`--self-contained` codegen is removed.** Generated code always imports the
-   now-standalone zero-dep `@ts-procedures/client`. This deletes an entire
-   `.ts`-regex-inlining subsystem (the single most fragile mechanism in the repo).
-4. **Scope is `@ts-procedures/*`** — self-documenting, on-brand, discoverable.
-
-The guiding principle throughout: **no magic, no bespoke build steps, no
-hand-maintained ordering.** Standard tools (`tsc -b`, Changesets,
-`verbatimModuleSyntax`, a one-time codemod) do the work.
-
----
-
-## 1. Overview & goals
-
-**What:** convert the single ESM package (`type: module`, `tsc`-built to
-`build/`) into an npm-workspaces monorepo under `packages/*`. Each export concern
-becomes its own scoped package under `@ts-procedures`. All scoped packages
-publish together at `1.0.0`.
-
-**Why:**
-- Independent install surface — a codegen-CLI user shouldn't pull the Hono
-  server runtime; an Astro-adapter user shouldn't pull `ajsc`.
-- Cleaner peer-dependency story per concern (`hono` only on `@ts-procedures/hono`,
-  `ajsc` only on `@ts-procedures/codegen`).
-
-**Honest trade-off:** a split improves *consumer* install surface at the cost of
-*maintainer* surface (7 packages, a codemod, cross-package test devDeps). This
-plan is engineered to keep that maintainer cost as low as possible — which is why
-several packages, a shim, and an inlining subsystem from earlier drafts are gone.
-
-**Constraints discovered during verification (still true, still respected):**
-- `ts-procedures` is published at `8.1.0`; it is **not** republished. New work
-  ships under `@ts-procedures/*`. The old name is deprecated in place.
-- `@ts-procedures/core` keeps `suretype`/`typebox` as **regular dependencies** —
-  there are unconditional top-level value imports (verified §9-B). They cannot be
-  optional peers.
-
----
-
-## 2. Target package set (7 packages)
-
-| Package | Responsibility | Owns (paths, relative to today's `src/`) | Internal deps | External deps | Peer deps |
-|---|---|---|---|---|---|
-| `@ts-procedures/core` | Procedures factory, `Create`/`CreateStream`/`CreateHttp`/`CreateHttpStream`, error classes, full schema pipeline, **+ all wire-contract types** (`DocEnvelope`, `AnyHttpRouteDoc` + RPC/API/Stream variants + `kind`, `ErrorDoc`, `HeaderDoc`, the `ErrorTaxonomy` *type alias*) **+ runtime-coupled config types** (`RPCConfig`, `APIConfig`, `FactoryItem`, `DocRegistryConfig` factory pieces). | `index.ts`, `create*.ts`, `errors.ts`, `stack-utils.ts`, `types.ts`, `exports.ts`, `schema/`, **+ the split of `implementations/types.ts`** (wire contract → `contract-types.ts`, runtime config → `config-types.ts`) | none | `ajv`, `ajv-formats`, `es-toolkit`, `suretype`, `typebox` | — |
-| `@ts-procedures/client` | Runtime client: `createClient`, fetch adapter, call/stream/SSE, hooks, request-builder, resolve-options, six client error classes + classifier, error-dispatch/registry, `RequestMeta`/`ClientErrorMap` augmentation interfaces. | `client/` | none (**zero-dep leaf**) | none | — |
-| `@ts-procedures/codegen` | Code-gen engine + `ts-procedures-codegen` bin. Loads `DocEnvelope`, groups by scope, emits TS/Kotlin/Swift. | `codegen/` (incl. `codegen/bin/cli.ts`), **minus** `emit-client-runtime.ts` / `emit-client-types.ts` (deleted with self-contained mode) | `@ts-procedures/core` (**type-only → devDependency**) | none at runtime | `ajsc` (dynamic-imported, optional) |
-| `@ts-procedures/http` | Framework-agnostic HTTP layer: `DocRegistry`, error-taxonomy registry (`defineErrorTaxonomy`, `defaultErrorTaxonomy`, `resolveErrorResponse`), `dispatchPreStreamError`/`dispatchMidStreamError`. | `implementations/http/doc-registry.ts`, `error-taxonomy.ts`, `error-dispatch.ts` + a new `index.ts` barrel | `@ts-procedures/core` | none | `hono` (type-only → optional) |
-| `@ts-procedures/hono` | Unified `HonoAppBuilder` (4 kinds), `toDocEnvelope()`, re-export of `defineErrorTaxonomy`. | `implementations/http/hono/` | `@ts-procedures/core`, `@ts-procedures/http` | `es-toolkit` | `hono` |
-| `@ts-procedures/astro` | Astro adapter: `createHandler`/`setAstroContext`/`stripPrefix`. Prod-clean (only `import type` from hono/astro). | `implementations/http/astro/` | none in prod (core+hono are test devDeps) | none | `astro`, `hono` |
-| `@ts-procedures/setup` | `ts-procedures-setup` bin + agent_config payload. **Explicit opt-in only — no `postinstall` hook.** | `agent_config/` | none | none | — |
-
-**`@ts-procedures/core` public entry:** `.` points at the **`exports.ts`** barrel
-(re-exports `index` + `errors` + `stack-utils` + schema modules + the contract
-types), not bare `index.ts`. `./errors` maps to `errors.ts`.
-
----
-
-## 3. Dependency graph (no cycles — by design, not by gymnastics)
-
-Putting the wire-contract types in `@ts-procedures/core` and using `import type`
-everywhere collapses every cycle the earlier draft fought:
-
-- **`implementations/types.ts` line 1 `import { Procedures }`** is value-imported
-  but used only in `ReturnType<typeof Procedures<…>>` (verified line 22). It moves
-  into core and becomes `import type` — a one-line change, no refactor.
-- **`error-taxonomy.ts` ↔ `types.ts`** (the old "Cycle A") dissolves: both
-  `ErrorDoc` and the `ErrorTaxonomy` *type* now live in core. The runtime
-  taxonomy helpers live in `@ts-procedures/http`, which depends on core in one
-  direction only.
-- **codegen → wire types** is 100% `import type` (verified: all 26 imports), so
-  it erases at compile time under `verbatimModuleSyntax`. `@ts-procedures/core`
-  is therefore a **devDependency** of codegen — CLI users install zero core
-  runtime.
-
-**Build order (derived automatically by `tsc -b`, never hand-maintained):**
-
-```
-@ts-procedures/core          (base: runtime + all contract types)
-@ts-procedures/client        (zero-dep leaf, parallel with core)
-   ↓
-@ts-procedures/http          (→ core; type-peer hono)
-@ts-procedures/codegen       (→ core type-only / devDep)
-   ↓
-@ts-procedures/hono          (→ core, http)
-   ↓
-@ts-procedures/astro         (prod-clean; devDeps core+hono)
-@ts-procedures/setup         (independent; agent_config only)
-```
-
-### One required source refactor before the move
-
-Split `src/implementations/types.ts` (lands in core):
-- **`contract-types.ts`** — pure wire contract: `DocEnvelope`,
-  `AnyHttpRouteDoc` + RPC/API/Stream variants + `kind`, `ErrorDoc`, `HeaderDoc`,
-  and the `ErrorTaxonomy` *type alias* (moved out of `error-taxonomy.ts`). Zero
-  value imports.
-- **`config-types.ts`** — runtime-coupled config: `RPCConfig`, `APIConfig`,
-  `FactoryItem`, `ProceduresFactory`/`ProceduresContext` helpers, and the
-  factory-referencing parts of `DocRegistryConfig`. `import type { Procedures }`
-  (not a value import).
-
-Turning on `verbatimModuleSyntax` proves `contract-types.ts` has zero value
-imports at compile time.
-
----
-
-## 4. Repository layout
-
-```
-ts-procedures/                       (workspace root, private: true)
-├── package.json                     workspaces: ["packages/*"], script orchestration
-├── tsconfig.base.json               shared compiler options
-├── tsconfig.json                    solution file: references all packages
-├── eslint.config.js                 shared; adds no-relative-packages rule
-├── vitest.config.ts                 projects mode (one project per package)
-├── .prettierrc
-├── .changeset/                      changesets config (fixed group) + entries
-├── .github/workflows/release.yml    NEW — OIDC provenance publish
-├── scripts/                         check-docs + release helpers
-└── packages/
-    ├── core/      src/{index,create*,errors,stack-utils,types,exports,
-    │                    contract-types,config-types}.ts + src/schema/
-    ├── client/    src/*.ts          (former src/client/*)
-    ├── codegen/   src/** + src/bin/cli.ts   (no client-snapshot, no self-contained emitters)
-    ├── http/      src/{index,doc-registry,error-taxonomy,error-dispatch}.ts
-    ├── hono/      src/**            (former src/implementations/http/hono/*)
-    ├── astro/     src/**            (former src/implementations/http/astro/*)
-    └── setup/     bin/{setup,postinstall}.mjs, lib/, claude-code/, cursor/, copilot/
-```
-
-> `setup/` still *ships* `postinstall.mjs` (so `npx @ts-procedures/setup` and the
-> existing auto-update logic remains available), but **no package wires it
-> as a `scripts.postinstall`** — see §7.
-
-### Root `package.json`
-
-```jsonc
-{
-  "name": "ts-procedures-monorepo",
-  "private": true,
-  "type": "module",
-  "workspaces": ["packages/*"],
-  "scripts": {
-    "build": "tsc -b",
-    "lint": "eslint packages/*/src --quiet",
-    "test": "vitest run",
-    "check-docs": "bash scripts/check-docs-consistency.sh",
-    "release": "changeset publish"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.x",
-    "typescript": "^5.x",
-    "vitest": "^x",
-    "eslint": "^9.x",
-    "eslint-plugin-import": "^2.x"
-  }
-}
-```
-
-### Root `tsconfig.base.json` (extended by every package)
-
-```jsonc
-{
-  "compilerOptions": {
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "target": "ES2022",
-    "strict": true,
-    "declaration": true,
-    "declarationMap": true,
-    "composite": true,
-    "verbatimModuleSyntax": true,
-    "outDir": "dist",
-    "rootDir": "src"
-  }
-}
-```
-
-> `verbatimModuleSyntax` is **off** today. Turning it on surfaces every
-> value-vs-type import mistake (e.g. the `import { Procedures }` in types.ts) at
-> compile time — which is exactly what we want before the split. Every
-> cross-package type-only import becomes `import type`.
-
-### Root `tsconfig.json` (solution / project references)
-
-```jsonc
-{
-  "files": [],
-  "references": [
-    { "path": "packages/core" },
-    { "path": "packages/client" },
-    { "path": "packages/http" },
-    { "path": "packages/codegen" },
-    { "path": "packages/hono" },
-    { "path": "packages/astro" }
-  ]
-}
-```
-
-Each package's `tsconfig.json` extends the base and lists `references` mirroring
-its internal deps. `setup` has no TS build (it's `.mjs` payload).
-
----
-
-## 5. Per-package `package.json` blueprints
-
-All scoped packages: `"version": "1.0.0"`, `"type": "module"`,
-`"publishConfig": { "access": "public", "provenance": true }`,
-`"repository": { "type": "git", "url": "...", "directory": "packages/<name>" }`.
-
-### `@ts-procedures/core`
-```jsonc
-{
-  "name": "@ts-procedures/core", "version": "1.0.0", "type": "module",
-  "exports": {
-    ".":       { "types": "./dist/exports.d.ts", "import": "./dist/exports.js" },
-    "./errors":{ "types": "./dist/errors.d.ts",  "import": "./dist/errors.js" }
-  },
-  "files": ["dist"],
-  "dependencies": {
-    "ajv": "^8.17.1", "ajv-formats": "^3.0.1", "es-toolkit": "^1.44.0",
-    "suretype": "^3.3.1", "typebox": "^1.0.30"
-  },
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> `.` points at the `exports.ts` barrel (which now also re-exports the contract
-> types). `suretype`+`typebox` stay regular deps (§9-B).
-
-### `@ts-procedures/client`
-```jsonc
-{
-  "name": "@ts-procedures/client", "version": "1.0.0", "type": "module",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist"],
-  "dependencies": {},
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> Genuine zero-dep leaf. No longer ships `src` (the snapshot consumer is gone).
-> The single runtime dependency that generated code now carries.
-
-### `@ts-procedures/codegen`
-```jsonc
-{
-  "name": "@ts-procedures/codegen", "version": "1.0.0", "type": "module",
-  "bin": { "ts-procedures-codegen": "./dist/bin/cli.js" },
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist"],
-  "peerDependencies": { "ajsc": "*" },
-  "peerDependenciesMeta": { "ajsc": { "optional": true } },
-  "devDependencies": {
-    "@ts-procedures/core": "workspace:*",
-    "@ts-procedures/client": "workspace:*"
-  },
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> `@ts-procedures/core` is a **devDependency** — codegen's use of contract types
-> is 100% `import type`, erased at build. `@ts-procedures/client` is a devDep for
-> the e2e test that compiles generated output. No `prebuild` snapshot script, no
-> self-contained emitters. Bin name `ts-procedures-codegen` and config filename
-> `ts-procedures-codegen.config.json` unchanged; preserve the `cli.ts` shebang.
-
-### `@ts-procedures/http`
-```jsonc
-{
-  "name": "@ts-procedures/http", "version": "1.0.0", "type": "module",
-  "exports": {
-    ".":        { "types": "./dist/index.d.ts",          "import": "./dist/index.js" },
-    "./docs":   { "types": "./dist/doc-registry.d.ts",   "import": "./dist/doc-registry.js" },
-    "./errors": { "types": "./dist/error-taxonomy.d.ts", "import": "./dist/error-taxonomy.js" }
-  },
-  "files": ["dist"],
-  "dependencies": { "@ts-procedures/core": "workspace:*" },
-  "peerDependencies": { "hono": "*" },
-  "peerDependenciesMeta": { "hono": { "optional": true } },
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> Author a new `src/index.ts` barrel (none exists today). `hono` is type-only
-> (`error-dispatch.ts`'s `import type { Context }`) → optional peer.
-
-### `@ts-procedures/hono`
-```jsonc
-{
-  "name": "@ts-procedures/hono", "version": "1.0.0", "type": "module",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist"],
-  "dependencies": {
-    "@ts-procedures/core": "workspace:*", "@ts-procedures/http": "workspace:*",
-    "es-toolkit": "^1.44.0"
-  },
-  "peerDependencies": { "hono": "*" },
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> `es-toolkit` is a **direct** dep (`path.ts` imports `es-toolkit/string` +
-> `es-toolkit/compat`). `hono` is a required peer.
-
-### `@ts-procedures/astro`
-```jsonc
-{
-  "name": "@ts-procedures/astro", "version": "1.0.0", "type": "module",
-  "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } },
-  "files": ["dist"],
-  "dependencies": {},
-  "peerDependencies": { "astro": "*", "hono": "*" },
-  "devDependencies": {
-    "@ts-procedures/core": "workspace:*", "@ts-procedures/hono": "workspace:*"
-  },
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> Prod-clean. `astro`+`hono` required peers. core+hono are test-only devDeps.
-
-### `@ts-procedures/setup`
-```jsonc
-{
-  "name": "@ts-procedures/setup", "version": "1.0.0", "type": "module",
-  "bin": { "ts-procedures-setup": "./bin/setup.mjs" },
-  "exports": { "./package.json": "./package.json" },
-  "files": ["bin", "lib", "claude-code", "cursor", "copilot"],
-  "publishConfig": { "access": "public", "provenance": true }
-}
-```
-> **No `scripts.postinstall`** (§7). Verify `setup.mjs`'s `resolve(__dirname, '..')`
-> payload resolution still lands on `claude-code/` etc. after the move; smoke-test
-> with `npm pack` + `npx -p <tarball>`.
-
----
-
-## 6. Tooling
-
-**TS build:** project references + `composite: true`; `tsc -b` from root derives
-order. `declarationMap: true` for cross-package go-to-definition.
-
-**Task runner:** `tsc -b` + `npm run --workspaces`. No Turborepo for v1.0.0 — add
-caching later only if build time becomes a problem.
-
-**`verbatimModuleSyntax`:** on. Forces correct `import type` everywhere.
-
-**Import rewrites (`../*.js` → `@ts-procedures/*`):** pervasive; **do not
-hand-edit.** Use a one-time ts-morph codemod with an explicit ownedPath→package
-map, then enforce with `eslint-plugin-import`'s `no-relative-packages` so CI fails
-on any surviving deep relative cross-package import.
-
-**vitest:** projects mode, one project per package, each typecheck pointing at its
-own `tsconfig`. The two `*.test-d.ts` files (`client/result-type.test-d.ts`,
-`client/augment-error-map.test-d.ts`) live with `@ts-procedures/client`.
-
-**Cross-package test cycles (devDep-only):**
-- `client/typed-error-dispatch.test.ts` imports core + hono.
-- `astro/index.test.ts` imports core + hono.
-- codegen e2e (`run-tsc.ts`) shells to `node_modules/.bin/tsc` and resolves
-  `@ts-procedures/*` specifiers — needs them hoisted + listed as codegen devDeps.
-
-Keep these as **devDependencies only.** CI assertion: no `@ts-procedures/*`
-package may list another in `dependencies` outside its declared internal-dep set.
-Verify `@ts-procedures/client`'s published `dependencies` stays empty via
-`npm pack --dry-run`. Optionally relocate the two spanning tests into a private
-(unpublished) `@ts-procedures/integration-tests` package.
-
-**Declaration-merging modules:** `RequestMeta` / `ClientErrorMap` live in
-`client/types.ts`. Augmentation target changes from `declare module
-'ts-procedures/client'` → `declare module '@ts-procedures/client'`. Add a
-`*.test-d.ts` that augments via the new specifier and asserts the merge.
-
----
-
-## 7. Versioning, publishing & the prior name
-
-**Tool:** **Changesets** (`@changesets/cli`). npm workspaces has no reliable
-`workspace:*`→range rewrite on publish; Changesets rewrites `workspace:*` into the
-concrete just-published range and publishes in topological order atomically.
-
-**Mode:** **fixed / lockstep** for the whole `@ts-procedures/*` set. The runtime
-coupling (http→core, hono→core+http) makes independent versions drift into peer
-mismatches. Lockstep also makes `workspace:*`→`^1.0.0` trivial.
-
-**v1.0.0 cut:** all scoped packages → `1.0.0` together.
-
-**No meta-package.** A `ts-procedures@9` re-export shim would ship zero real
-changes — pointless churn. Instead:
-- Publish `@ts-procedures/*` fresh.
-- `npm deprecate "ts-procedures" "Moved to @ts-procedures/*. See migration guide: <url>"`
-  — the old `8.1.0` stays installable (no break for pinned consumers) but warns.
-- Existing `ts-procedures@8` installs keep their current `postinstall`
-  auto-updater (frozen, harmless). New consumers opt in explicitly via
-  `npx @ts-procedures/setup`.
-
-**Why no auto-postinstall on the new packages:** a `postinstall` that silently
-mutates a consumer's repo is itself anti-DX/magic, and on a split it would have to
-live on a deep lib everyone installs (`@ts-procedures/core`) — wrong place.
-Explicit `npx @ts-procedures/setup` is the clean, predictable replacement.
-
-**Provenance & access (both missing today):**
-- Every package: `publishConfig.access: "public"` (scoped packages are private by
-  default — without this, publish fails 402 or publishes privately).
-- Stand up `.github/workflows/release.yml` with `permissions: id-token: write` and
-  `npm publish --provenance` via `changesets/action`. Add `repository.directory`
-  per package.
-- **Prereq:** claim the `@ts-procedures` npm org/scope with publish rights before
-  release.
-
-**`prepublishOnly` / docs gate:** `check-docs` is a **repo-wide** invariant scan —
-keep it as a single **root CI gate** before any publish. Per-package
-`prepublishOnly` is at most `lint && build`.
-
----
-
-## 8. Consumer migration & breaking changes
-
-This is a **hard import cutover** — there is no shim. Document prominently.
-
-### Old import → new import
-
-| Today | New |
-|---|---|
-| `ts-procedures` (`.`) | `@ts-procedures/core` |
-| `ts-procedures/client` | `@ts-procedures/client` |
-| `ts-procedures/codegen` | `@ts-procedures/codegen` |
-| `ts-procedures/hono` | `@ts-procedures/hono` |
-| `ts-procedures/astro` | `@ts-procedures/astro` |
-| `ts-procedures/http` (**types-only**) | `@ts-procedures/core` (contract types now live here; still types-only at use sites via `import type`) |
-| `ts-procedures/http-docs` | `@ts-procedures/http/docs` |
-| `ts-procedures/http-errors` | `@ts-procedures/http/errors` |
-
-> The codemod must use this per-subpath table, not a regex — `ts-procedures/http`
-> does **not** map to `@ts-procedures/http`.
-
-### Codegen: `--self-contained` removed, `clientImportPath` default flips
-- `--self-contained` / `--no-self-contained`, the `selfContained` option, and the
-  `emit-client-runtime.ts` / `emit-client-types.ts` emitters are **deleted**.
-  Generated code always imports `@ts-procedures/client`. Consumers add it as a
-  (zero-dep) dependency — documented as required.
-- Default `clientImportPath` changes from `'ts-procedures/client'`
-  (verified: `emit-index.ts:35`, `emit-scope.ts:769`) to `'@ts-procedures/client'`.
-  Update the ~5 test expectations (emit-scope/emit-index/pipeline/e2e). Update
-  CLAUDE.md and `docs/` to drop all self-contained references.
-
-### Hardcoded `ts-procedures` strings that ship downstream
-- **agent_config** (21 files, ~239 refs): skills, `patterns.md`,
-  `anti-patterns.md`, `api-reference.md`, scaffold templates,
-  `copilot-instructions.md`, `cursorrules`. Rewrite all to scoped names in the
-  migration PR.
-- **docs/** (`core.md`, `http-integrations.md`, `astro-adapter.md`,
-  `client-and-codegen.md`, `client-error-handling.md`, `streaming.md`): sweep
-  alongside. (`docs/superpowers/plans|specs/*` are historical — leave them.)
-- Extend `scripts/check-docs-consistency.sh` to grep agent_config + docs for bare
-  `ts-procedures` import strings and fail CI.
-
-### Bin & config names — preserved
-`ts-procedures-codegen` (on `@ts-procedures/codegen`) and `ts-procedures-setup`
-(on `@ts-procedures/setup`) keep their bin names; `ts-procedures-codegen.config.json`
-keeps its name.
-
-### Expected churn
-First post-upgrade regeneration produces an import-path + source-hash diff across
-all generated files. Document as expected, not a regression.
-
----
-
-## 9. Step-by-step migration sequence
-
-Each step is verifiable. **Steps 1–3 are prerequisite refactors on the current
-single package** (must land and ship working before any directory move).
-
-**Phase 0 — De-risk in place (no split yet)**
-1. **Split `implementations/types.ts`** into `contract-types.ts` (wire contract,
-   incl. the `ErrorTaxonomy` type moved out of `error-taxonomy.ts`) and
-   `config-types.ts` (runtime-coupled). Change `import { Procedures }` →
-   `import type`. Turn on `verbatimModuleSyntax` locally to prove `contract-types.ts`
-   has zero value imports. `npm run build` green; `madge --circular src` clean.
-2. **Remove self-contained codegen:** delete `emit-client-runtime.ts` /
-   `emit-client-types.ts` and the `selfContained` branch; make generated code
-   always import from `clientImportPath` (default flips to `@ts-procedures/client`
-   in step 12). Update affected tests. `npm test` green.
-3. **Confirm schema-lib deps:** keep `suretype`+`typebox` as regular deps (§9-B).
-
-**Phase 1 — Scaffold workspace**
-4. Create `packages/`, root `package.json` (`workspaces`, `private`),
-   `tsconfig.base.json`, solution `tsconfig.json`, `vitest.config.ts` projects
-   mode, eslint `no-relative-packages`.
-
-**Phase 2 — Move files per package (in build order)**
-5. `git mv` per §4: core → client → http → codegen → hono → astro → setup.
-   Keep history with `git mv`.
-6. Write each package's `package.json` (§5) and `tsconfig.json`.
-
-**Phase 3 — Rewrite imports & wire references**
-7. Run the ts-morph codemod (ownedPath→`@ts-procedures/*` map, §8 table for the
-   `./http` → core cases).
-8. `tsc -b` from root. Iterate until green. eslint passes.
-
-**Phase 4 — Tests**
-9. Move test files with their packages; add test-only devDeps (client→hono/core,
-   astro→hono/core, codegen→client/core). `vitest run` green across all projects,
-   including `*.test-d.ts` typecheck and codegen e2e.
-10. Add the declaration-merge `*.test-d.ts` asserting `@ts-procedures/client`
-    augmentation works.
-
-**Phase 5 — Codegen output default**
-11. Confirm default `clientImportPath` = `'@ts-procedures/client'`; update the ~5
-    test expectations. Build + test green.
-
-**Phase 6 — Docs / agent_config**
-12. Rewrite all `ts-procedures` import strings in agent_config + docs to scoped
-    names; drop self-contained docs. Extend `check-docs-consistency.sh`;
-    `npm run check-docs` green.
-
-**Phase 7 — Release engineering**
-13. `npx changeset init`; configure `fixed` group for `@ts-procedures/*`. Add the
-    v1.0.0 changeset.
-14. Create `.github/workflows/release.yml` (OIDC, `--provenance`,
-    `changesets/action`). Add `repository.directory` per package. Claim the
-    `@ts-procedures` npm org.
-15. Dry-run: `npm pack --dry-run` each package; assert `files` correct and no
-    stray `@ts-procedures/*` in published `dependencies`.
-
-**Phase 8 — Publish & deprecate**
-16. CI runs root `lint && build && check-docs && test`, then `changeset publish`
-    → all `@ts-procedures/*` at 1.0.0 with `workspace:*` rewritten to `^1.0.0`,
-    provenance attached.
-17. `npm deprecate "ts-procedures" "Moved to @ts-procedures/*; see migration guide"`.
-18. Smoke-test a fresh consumer: install `@ts-procedures/codegen` +
-    `@ts-procedures/client`, run `npx ts-procedures-codegen` against a sample
-    envelope; assert generated imports resolve and compile.
-
----
-
-## 10. Risks (consolidated)
-
-The original draft's blockers 10-A (self-contained disk read), 10-C/10-D
-(http-protocol cycles), 10-G (prior-version conflict), and 10-H (postinstall
-reach) are **designed out** by the four decisions in the header. What remains:
-
-### MUST-DO before publish
-- **Scoped packages are private by default + no CI/provenance exist.** Add
-  `publishConfig.access: public` to all packages; stand up the OIDC release
-  workflow; claim the `@ts-procedures` org. (was 10-E)
-- **`workspace:*` has no rewrite under raw `npm publish`.** Changesets (fixed
-  mode) handles it. (was 10-F)
-
-### Keep in mind (§9-B) `@ts-procedures/core` deps
-Verified unconditional top-level value imports: `extract-json-schema.ts:1`
-(`extractSingleJsonSchema` from `suretype`), `resolve-schema-lib.ts:1-2`
-(`CoreValidator` from `suretype`, `Type` from `typebox`), `schema/types.ts:1-2`
-(both). Optional peers → `ERR_MODULE_NOT_FOUND`. **Keep both as regular
-dependencies.** (Optional future: lazy `import('suretype')` inside the suretype
-branch + `import type` for the type-only names, then consider dropping suretype.)
-
-### Lower-risk items to not forget
-- `@ts-procedures/core` `.` must point at `exports.ts`, not `index.ts`.
-- `@ts-procedures/http` needs a new `index.ts` barrel authored.
-- `es-toolkit` must be a **direct** dep of both core and hono (deep subpaths;
-  don't rely on hoisting).
-- `@ts-procedures/setup` bin payload resolution (`resolve(__dirname, '..')`)
-  re-verified after the move; payload dirs in `files`.
-- `RequestMeta`/`ClientErrorMap` augmentation specifier change — silent if missed;
-  cover with `*.test-d.ts`.
-- Preserve `cli.ts` shebang through compilation; bin path `./dist/bin/cli.js`.
-- Generated-file diff churn on first regen — document as expected.
-
----
-
-## 11. Open questions for the maintainer
-
-Resolved by decision: meta-package (none), versioning (lockstep 1.0.0),
-self-contained (removed), scope name (`@ts-procedures`), http-protocol package
-(collapsed into core). Remaining:
-
-1. **`@ts-procedures/http` — one package vs split into `@ts-procedures/http-docs`
-   + `@ts-procedures/http-errors`?** Recommendation: **one package** with
-   `./docs`/`./errors` subpaths (doc-registry imports error-taxonomy at runtime).
-   Split only if a consumer wants the taxonomy without DocRegistry.
-2. **suretype's future:** keep as a regular dep of `@ts-procedures/core` for
-   v1.0.0 (required — §9-B), or invest in the lazy-import refactor now and consider
-   dropping suretype (documented as deprecated/legacy)?
-3. **Integration tests:** relocate the spanning tests
-   (`client/typed-error-dispatch.test.ts`, `astro/index.test.ts`) into a private
-   `@ts-procedures/integration-tests` package, or keep them in-package with
-   devDep edges?
-4. **Migration guide URL:** where does the `npm deprecate` message point — a
-   `MIGRATION.md` in the repo, a docs site page, or a GitHub release?