ts-procedures 8.1.0 → 8.1.1

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

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

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "ts-procedures",
-  "version": "8.1.0",
+  "version": "8.1.1",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
   "type": "module",
+  "sideEffects": false,
   "bin": {
     "ts-procedures-setup": "./agent_config/bin/setup.mjs",
     "ts-procedures-codegen": "./build/codegen/bin/cli.js"

package/src/client/errors.ts

@@ -27,7 +27,7 @@ export class ClientHttpError extends Error {
 }
 
 /** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
-// eslint-disable-next-line no-redeclare
+ 
 export const ClientRequestError = ClientHttpError
 /** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
 // eslint-disable-next-line no-redeclare

package/src/client/typed-error-dispatch.test.ts

@@ -1,8 +1,7 @@
-/* eslint-disable @typescript-eslint/no-empty-object-type */
+ 
 import { describe, expect, test } from 'vitest'
 import { Type } from 'typebox'
 import { Procedures } from '../index.js'
-import { APIConfig } from '../implementations/types.js'
 import { HonoAppBuilder, defineErrorTaxonomy } from '../implementations/http/hono/index.js'
 import { createClient } from './index.js'
 import { ClientRequestError } from './errors.js'

package/src/codegen/bundle-size.test.ts

@@ -69,7 +69,7 @@ describe('bundle size budget', () => {
     // This isn't a strict assertion — it surfaces the actual numbers to the
     // test output so reviewers can update PERROUTEDELTA_BASELINE in the
     // comment above without having to re-run locally.
-    // eslint-disable-next-line no-console
+     
     console.log(`[bundle-size] 100 routes, scope file = ${totalChars} chars stripped, per-route = ${perRouteDelta.toFixed(1)}`)
     expect(totalChars).toBeGreaterThan(0)
   })

package/src/codegen/test-helpers/golden.ts

@@ -22,7 +22,7 @@ export async function assertGoldenOrUpdate(produced: string, goldenPath: string)
       '// Source hash: <PLACEHOLDER>',
     )
     await writeFile(goldenPath, goldenContent, 'utf-8')
-    // eslint-disable-next-line no-console
+     
     console.log(`[golden-test] Wrote golden: ${goldenPath}`)
     return
   }