ts-procedures 6.0.2 → 6.2.0

package/docs/superpowers/specs/2026-04-24-kotlin-swift-codegen-design.md

@@ -1,6 +1,6 @@
 # Kotlin & Swift Codegen for ts-procedures
 
-**Status:** Design
+**Status:** Shipped (both targets — Kotlin and Swift)
 **Date:** 2026-04-24
 **Author:** Cory Robinson
 **Implementation order:** Kotlin first, Swift second.

package/docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md

@@ -0,0 +1,314 @@
+# ajsc v7.2 Kotlin Codegen Polish
+
+**Status:** Shipped
+**Date:** 2026-04-25
+**Author:** Cory Robinson
+**Supersedes parts of:** [`2026-04-24-kotlin-swift-codegen-design.md`](./2026-04-24-kotlin-swift-codegen-design.md) — Kotlin sections only. Swift sections of the prior design remain in force and unscheduled.
+**Scope:** Polish the existing `codegen-kotlin-swift` branch's Kotlin target to align with `ajsc@^7.2.0`. No Swift work in this round.
+
+## Context
+
+The original Kotlin codegen design ([2026-04-24](./2026-04-24-kotlin-swift-codegen-design.md)) anticipated an "ajsc Phase A" delivery exposing `emitKotlin`. ajsc shipped that and more in `7.0` → `7.1` → `7.2`:
+
+- **`7.0`** delivered `emitKotlin` and `emitSwift` with the `EmitResult` shape the prior spec specified.
+- **`7.1`** added `nameRegistry: Set<string>` + `namePrefix: string` to make cross-call dedup tractable when concatenating multiple slot emissions into one namespace.
+- **`7.2`** added `inlineTypes?: boolean` (default `false`). When `true`, nested object types emit as **nested classes inside their parent's body** instead of extracting to top-level siblings. Kotlin's nested-class scoping makes `Body.Address` and `Response.Address` different fully-qualified names — collisions become structurally impossible without any shared state.
+
+The current branch implementation predates `7.1` and `7.2`. It calls `emitKotlin` once per slot with no shared registry, which is a correctness bug for any schema that has structurally-identical sub-objects in two slots (Kotlin emits `data class Address(...)` from both calls → duplicate-class compile error).
+
+This polish round adopts `inlineTypes: true` as the routing strategy, drops dead options from our adapter contract, surfaces `serializer` and `unsupportedUnions` as CLI flags, replaces the trivial test fixture with a realistic one, activates the gated `kotlinc` E2E test, and ships a downstream-consumer setup guide.
+
+## Goals
+
+1. **Correctness**: generated Kotlin compiles for realistic schemas (shared sub-types across slots, discriminated unions, `format: date-time` fields, JSON-key sanitization).
+2. **Clean separation of concerns**: ajsc emits declarations; `ts-procedures` wraps and writes files. No shared state across `emit` calls in our code.
+3. **Easy-to-follow code**: route emitter is a pure function — same inputs, same output, no per-call coordination logic.
+4. **Strong downstream DX**: a typed Android/iOS dev integrating generated output gets a clear setup guide covering Gradle deps, contextual serializers, sealed-interface decoding, and the `serializer: 'none'` escape hatch.
+5. **Forward-compat**: changes are additive on the CLI surface and conservative on defaults so future Swift work and future ajsc releases land cleanly.
+
+## Non-goals
+
+- **Swift target.** Stays deferred. The architecture sketched here generalizes naturally — same per-slot loop, same `inlineTypes: true` strategy — but a separate spec will cover Swift-specific idioms (`Codable`, `AnyCodable` fallback shape, `accessLevel`).
+- **Cross-route shared types.** No `Shared.User` extraction. Each route's types live under its own `object`.
+- **Streaming routes.** Skipped with a single summary log line, as in the original spec.
+- **Hooks, per-call options, error registry, base-URL handling.** All deferred per the prior spec; nothing changes.
+- **Mid-PR changes to TS target output.** The TS codegen path is untouched.
+- **`agent_config/` distribution updates.** Codegen targets are not agent-relevant content.
+
+## Architecture & boundary
+
+The contract between ajsc and `ts-procedures` is unchanged from the original spec: ajsc emits **declarations only** (no `package`, no `import` lines); `ts-procedures` assembles the file (`package` line, deduped imports, scope/route wrappers, source-hash header).
+
+```
+DocEnvelope
+  → resolveEnvelope
+  → groupRoutesByScope
+  → for each scope:
+       → for each route:
+            → for each slot in [pathParams, query, body, response, ...errors]:
+                 emitKotlin(slotSchema, { rootTypeName: slot.name, inlineTypes: true, serializer, unsupportedUnions, ...passthrough })
+            → wrap collected emissions in `object RouteName { method, pathTemplate, path(...) | const path, ...slots, Errors? }`
+       → wrap routes in `object Scope { ... }`
+       → prepend package + source-hash + imports
+       → write Scope.kt
+```
+
+Two architectural decisions:
+
+- **`packageName` opt is not passed to ajsc.** The scope emitter writes `package com.example.api` itself. Keeps the boundary "ajsc gives declarations, we assemble files" intact and avoids any (untested) interaction of v7.2's `packageName` opt with the `code` body.
+- **No shared state across emit calls.** Per-route registry plumbing (`nameRegistry` / `namePrefix`) is **not** used. `inlineTypes: true` makes it unnecessary because nested-class scoping is structural.
+
+## Adapter contract — `KotlinEmitOptions` final shape
+
+```ts
+export interface KotlinEmitOptions {
+  rootTypeName: string                          // required — slot name (Body, Response, NotFound, ...)
+  inlineTypes?: boolean                         // we always pass true
+  serializer?: 'kotlinx' | 'none'               // CLI flag, default 'kotlinx'
+  unsupportedUnions?: 'throw' | 'fallback'      // CLI flag, default 'throw'
+  arrayItemNaming?: string | false              // pass-through (existing CLI flag)
+  depluralize?: boolean                         // pass-through (existing CLI flag)
+  uncountableWords?: string[]                   // pass-through (existing CLI flag)
+}
+```
+
+**Removed from the existing branch's adapter:**
+
+- `inlineTypes` previously typed as a knob — now hardcoded `true` (still on the type but never set by callers other than ourselves).
+- `enumStyle` — TypeScript-only ajsc opt; never honored by `KotlinConverterOpts`.
+
+**Not used by us (but valid in ajsc):** `nameRegistry`, `namePrefix`, `packageName`, `unsupportedUnions: 'fallback'` for already-decided opt-in flow.
+
+The `KotlinEmitter` interface stays `emit(schema, opts) → KotlinEmitResult`. The production resolver collapses to a one-liner:
+
+```ts
+return { emit: (schema, opts) => emitKotlin(schema, opts) }
+```
+
+The stub factory (`createStubKotlinEmitter`) used in unit/integration tests stays the same shape — keyed on `rootTypeName`, returns hand-authored `KotlinEmitResult` objects.
+
+## Per-route emission
+
+`emit-route-kotlin.ts` becomes a pure function — no shared `Set<string>`, no prefix arithmetic:
+
+```
+emitKotlinRoute(route, emitter, errorSchemas, { serializer, unsupportedUnions, ...passthrough }):
+  if route.kind === 'stream' → return { code: '', imports: [], routeName, skipped: true }
+
+  emit lines:
+    `const val method = "<method>"`
+    `const val pathTemplate = "<bracePath>"`
+    `fun path(p: PathParams): String = "<interpolated>"`   if path params present
+    `const val path = "<bracePath>"`                       otherwise
+
+  for each slot in [pathParams, query, body, response]:
+    if slot.schema is null, skip
+    result = emitter.emit(slot.schema, { rootTypeName: slot.name, inlineTypes: true, serializer, unsupportedUnions, ...passthrough })
+    push result.code, result.imports
+
+  for each errorKey in route.errors:
+    if errorSchemas.has(errorKey):
+      result = emitter.emit(errorSchemas.get(errorKey), { rootTypeName: errorKey, inlineTypes: true, serializer, unsupportedUnions, ...passthrough })
+      collect into Errors namespace
+  if any errors emitted, append wrapped `object Errors { ... }`
+
+  return { code, imports, routeName, skipped: false }
+```
+
+Slot emit order is fixed: `pathParams → query → body → response → errors[]`. Deterministic output is required for the source-hash staleness check.
+
+**Stream-skip:** the route emitter returns `skipped: true`; the pipeline collects names and logs **one summary line** at end of run. No per-route warnings during emission.
+
+## Pipeline & CLI
+
+### `PipelineOptions` additions
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `target` | `'ts' \| 'kotlin'` | `'ts'` | unchanged |
+| `kotlinPackage` | `string` | — | required when `target === 'kotlin'` |
+| `kotlinSerializer` | `'kotlinx' \| 'none'` | `'kotlinx'` | new |
+| `unsupportedUnions` | `'throw' \| 'fallback'` | `'throw'` | new — top-level (not Kotlin-nested) so name stays stable when Swift lands |
+| `kotlinEmitter` | `KotlinEmitter \| undefined` | — | injected for tests; production CLI resolves via `resolveProductionKotlinEmitter()` |
+
+### CLI flags
+
+| Flag | Maps to | Notes |
+|---|---|---|
+| `--target <ts\|kotlin>` | `target` | unchanged |
+| `--kotlin-package <pkg>` | `kotlinPackage` | unchanged; required when `target=kotlin` |
+| `--kotlin-serializer <kotlinx\|none>` | `kotlinSerializer` | new |
+| `--unsupported-unions <throw\|fallback>` | `unsupportedUnions` | new |
+| `--array-item-naming`, `--depluralize`, `--uncountable-words` | `KotlinEmitOptions` pass-through | existing TS-target flags, now also applied to Kotlin target |
+
+**Silently ignored under `--target ts`:** `--kotlin-serializer`. **Silently ignored under `--target kotlin`:** `--service-name`, `--namespace-types`, `--self-contained`, `--client-import-path`, `--jsdoc` (matches existing behavior).
+
+### Config-file mapping
+
+```json
+{
+  "target": "kotlin",
+  "kotlin": { "package": "com.example.api", "serializer": "kotlinx" },
+  "unsupportedUnions": "throw",
+  "url": "https://api.example.com/_ts-procedures.json",
+  "out": "./generated"
+}
+```
+
+CLI flags override config values. `--kotlin-serializer none` works regardless of imports — ajsc decides.
+
+### Where parsed values land
+
+The existing `parseArgs` returns `ParsedArgs` with `parsed.kotlin.package` for the package flag. The new fields slot in the same way:
+
+| CLI flag | Lands at | Rationale |
+|---|---|---|
+| `--kotlin-serializer` | `parsed.kotlin.serializer` | Kotlin-specific knob — nests under `kotlin` like `package` |
+| `--unsupported-unions` | `parsed.unsupportedUnions` | Top-level — forward-compat for Swift and any future target |
+
+### Behavior under `--target ts`
+
+| Flag | TS-target behavior |
+|---|---|
+| `--kotlin-serializer` | silently ignored (Kotlin-only knob) |
+| `--unsupported-unions` | **threaded through** to TS emit unconditionally — it is a no-op in ajsc's TypeScript converter today, but threading it preserves forward-compat semantics |
+| `--kotlin-package` | silently ignored |
+
+### `--kotlin-inline-types` is intentionally not exposed
+
+Hardcoding `inlineTypes: true` is a deliberate design choice. The flat-types pattern (`nameRegistry` + `namePrefix`) remains supported by ajsc; if a consumer demands it later, an opt-out flag (`--kotlin-flat-types`) can be added additively without breaking existing output.
+
+## Testing strategy
+
+Four layers, each catching a distinct class of breakage. The current branch already has skeletons for three; this round updates assertions to v7.2 reality and adds the fourth (probe).
+
+### Realistic fixture (`__fixtures__/users-envelope.json`)
+
+Single source of truth for the integration golden and the kotlinc E2E. Replaces the existing `{ type: 'object' }` placeholder envelope. Contains:
+
+| Route | Exercises |
+|---|---|
+| `GET /users/:id` (`GetUser`) | path params + nested response object + nested address (two-level nesting → exercises `inlineTypes`) + `format: date-time` field (`@Contextual Instant`) + `created-at` JSON key (auto `@SerialName`) + one error (`NotFound`) |
+| `POST /users` (`CreateUser`) | no path params → `const val path` branch + body with discriminated `oneOf` (sealed interface emission) + one error (`ValidationError`) |
+| `GET /users` (`ListUsers`) | query params + array response + enum field (`status: 'active' \| 'inactive'`) → top-level enum extraction (always extracted regardless of `inlineTypes`) |
+
+Plus envelope-level `errors[]` with two error schemas so the route emitter's filter-by-key logic gets real signal.
+
+### Layer 1 — Unit tests (revised, unconditional, sub-second)
+
+Per-file 1:1 with current layout. Behavioral changes:
+
+- **`format-kotlin.test.ts`** — no changes.
+- **`ajsc-adapter.test.ts`** — drop `inlineTypes`/`enumStyle` from contract test; pin error-message text from `resolveProductionKotlinEmitter()` when `import('ajsc')` fails or `emitKotlin` is missing.
+- **`emit-route-kotlin.test.ts`** — drop registry/prefix assertions; add `expect(passedOpts.inlineTypes).toBe(true)` per slot; verify slot ordering; verify stream routes return `skipped: true` and empty code.
+- **`emit-scope-kotlin.test.ts`** — confirm imports deduped/sorted across all routes in a scope; no namespace-shape changes.
+
+### Layer 2 — Integration test (golden, stub emitter)
+
+`integration.test.ts` runs full `runPipeline` against the realistic fixture with a **stub** emitter returning hand-authored ajsc-style output (nested-class shape) per slot. Asserts byte-identical match against `__fixtures__/users-golden.kt`.
+
+**Why stub for integration:** pins our wrapping logic independent of ajsc version drift. If a future ajsc patch tweaks formatting whitespace, the golden test still passes; the kotlinc E2E catches semantic regressions. Separates "did our pipeline assemble the right file?" from "does ajsc still emit valid Kotlin?"
+
+Golden regenerated via `UPDATE_GOLDENS=1 npx vitest run integration.test.ts`. Source-hash line spliced from actual run.
+
+### Layer 3 — Kotlinc E2E compile test
+
+`e2e-compile.test.ts` runs the pipeline with the **production** ajsc emitter against the realistic fixture, writes output to a tmp dir, invokes `kotlinc` with `kotlinx-serialization-json` on classpath, asserts exit 0.
+
+**Gating:** `it.skipIf(!kotlincAvailable() || process.env.TS_PROCEDURES_KOTLIN_E2E !== '1')`. The ajsc Phase A check is removed — v7.2 is installed.
+
+**What this catches that nothing else does:** silent name-collision regressions, schema patterns producing uncompilable Kotlin (reserved-word edges), missing `@Contextual` annotations, sealed-interface scoping bugs.
+
+### Layer 4 — Probe test for `unsupportedUnions: 'fallback'` Kotlin behavior
+
+The v7.2 handoff specifies the **Swift** fallback shape (`AnyCodable` helper) but does not pin the **Kotlin** fallback shape. We need to know it before documenting the flag.
+
+`probe-unsupported-unions.test.ts` runs the real `emitKotlin` with `{ oneOf: [{ type: 'string' }, { type: 'integer' }] }` and `unsupportedUnions: 'fallback'`. Asserts via `toMatchSnapshot()` — captures whatever ajsc currently emits. The captured snapshot becomes the basis for the consumer doc's "untagged unions" section. If a future ajsc release changes the fallback shape, the snapshot diff surfaces it.
+
+**Gating:** `ajsc` is in `optionalDependencies`, so a contributor running `npm install --omit=optional` won't have it resolvable. The probe gates with the same toolchain-availability pattern as the E2E: `it.skipIf(!ajscResolvable())`. The check tries `import('ajsc')` once at module load and skips if the import throws. No kotlinc needed.
+
+## Downstream consumer documentation
+
+The highest-DX-impact deliverable in this plan. Without it, the first downstream Android dev hits "why won't `Json.decodeFromString` round-trip my `Instant`?" and the codegen feels broken.
+
+### New doc: `docs/codegen-kotlin.md`
+
+Self-contained setup guide. Outline:
+
+| Section | Content |
+|---|---|
+| Quickstart | `npx ts-procedures-codegen --target kotlin --kotlin-package com.example.api ...`; one `Users.kt` per scope; types accessed as `Users.GetUser.Response`, `Users.GetUser.Body.Address` (nested). |
+| Gradle setup | `kotlin("plugin.serialization")` + `kotlinx-serialization-json` dep with current pin; KMP non-support note (JVM only for now). |
+| Contextual serializers | What `@Contextual` means; copy-pasteable `Json { serializersModule = ... }` block; pointers to public Gist-quality serializers for `Instant`, `UUID`, `URI`, `LocalDate`, `LocalTime`. We recommend ISO-8601 to match server. |
+| Discriminated unions | `sealed interface` shape; `@JsonClassDiscriminator` is read automatically — no extra config. Wire format: discriminator field erased from variants under kotlinx mode. |
+| JSON-key sanitization | `first-name` → `firstName` with `@SerialName("first-name")` auto-emitted. Reserved words → trailing underscore. Nothing to configure. |
+| `--kotlin-serializer none` | Emit plain data classes with no annotations. Adapter setup is your own (Moshi, Gson, hand-written). Discriminator field is **retained** in variants under `none` mode. |
+| `--unsupported-unions fallback` | Kotlin fallback shape sourced from the Section "Layer 4" probe snapshot — **not authored speculatively**. Filled in once probe runs. |
+| Documented limitations | `additionalProperties: { type: T }` dropped with KDoc note; tuples >3 throw; `examples` dropped. What to do if you hit them. |
+
+**Distribution:** the doc lives in `docs/` of this repo. The CLI prints a one-line pointer after a successful Kotlin run:
+
+```
+[ts-procedures-codegen] Wrote 3 .kt files to ./generated. Setup guide: https://github.com/<org>/ts-procedures/blob/master/docs/codegen-kotlin.md
+```
+
+Once per invocation. No per-file boilerplate.
+
+### `CLAUDE.md` updates
+
+Small update to the existing "Kotlin target" bullet:
+
+- Output-shape change: `Users.GetUser.Body.Address` (nested) instead of `Users.GetUser.BodyAddress`.
+- New flags: `--kotlin-serializer <kotlinx|none>` (default `kotlinx`), `--unsupported-unions <throw|fallback>` (default `throw`).
+- Pointer to `docs/codegen-kotlin.md` for downstream consumer setup.
+
+## Migration / backwards-compatibility
+
+This polish lands on the unmerged `codegen-kotlin-swift` branch. Kotlin codegen has not shipped to a tagged release yet, so "migration" means "what changes between this branch's current state and the polished state."
+
+| Change | Visible to | Action |
+|---|---|---|
+| Output shape: flat → nested (`Body.Address`) | anyone testing the branch | Re-run codegen; references like `BodyAddress` become `Body.Address` |
+| Two new CLI flags | CLI users | None — defaults preserve prior behavior |
+| Realistic fixture replaces trivial one | reviewers of integration golden | Standard golden regeneration |
+| Unit test reshape | nobody outside this repo | None |
+| `optionalDependencies: ajsc` constraint bumps to `^7.2.0` | `package.json` consumers | npm install resolves it |
+
+When the branch ships, the `feat!` commit explicitly notes the nested-types output shape so downstream consumers reading the changelog know what to expect.
+
+## Risk assessment
+
+- **Risk: ajsc v7.2 emits subtly-different output for one of our fixture cases.** Mitigated by the kotlinc E2E test (compiles real ajsc output) plus the probe snapshot for `unsupportedUnions: 'fallback'`.
+- **Risk: realistic fixture is "realistic enough" but misses a pattern that breaks in production.** Mitigated by the layered test pyramid: unit tests pin our wrapping; integration golden pins file assembly; E2E compile pins ajsc semantics; probe pins ajsc-undocumented behavior. We close the loop in production by the first real consumer's feedback, not by trying to enumerate every schema shape upfront.
+- **Risk: nested-types DX is unintuitive for a shop expecting flat names.** Mitigated by the `--kotlin-flat-types` opt-out path remaining available in ajsc; we can add a CLI flag additively without breaking existing output. The handoff doc explicitly says both modes are supported indefinitely.
+- **Risk: Gradle / contextual-serializer setup is too much friction.** Mitigated by `docs/codegen-kotlin.md` having copy-pasteable blocks and serializer pointers, and by `--kotlin-serializer none` as a one-flag escape if a consumer's ecosystem can't accept the kotlinx Gradle plugin.
+- **Risk: CI does not have `kotlinc` available.** The E2E compile test gates on `TS_PROCEDURES_KOTLIN_E2E=1` and toolchain detection; CI without `kotlinc` skips it. Local runs and at-minimum manual pre-release runs catch what CI doesn't.
+
+## Open questions / explicit deferrals
+
+1. **CI integration of the kotlinc E2E.** Provisioning `kotlinc` + `kotlinx-serialization-json` in CI is a separate, optional decision. This spec ships the test gated; CI activation can follow once a maintainer wants it.
+2. **`UPDATE_GOLDENS=1` ergonomics.** Standard golden-test pattern. If we need richer affordances (per-test golden regeneration, partial-update flags), that's a separate quality-of-life PR.
+3. **Cross-route shared types** — still deferred per original spec.
+4. **Swift target** — still deferred. The architecture designed here generalizes naturally; a separate spec covers Swift idioms.
+5. **`--kotlin-flat-types` opt-out flag** — not exposed in this round. Additive when needed.
+
+## Sequencing (execution-order summary, plan deferred)
+
+This spec drives a single implementation plan. Execution-order intent:
+
+1. `KotlinEmitOptions` shape cleanup (drop `inlineTypes` knob from caller surface, keep hardcoded internally; drop `enumStyle`).
+2. `emit-route-kotlin.ts` → pure function (no registry/prefix); pass `inlineTypes: true`, `serializer`, `unsupportedUnions` per emit; stream routes return `skipped: true`.
+3. Pipeline-level summary log for skipped streams.
+4. CLI: add `--kotlin-serializer`, `--unsupported-unions` flags; thread through.
+5. Realistic fixture replacement; regenerate integration golden.
+6. Probe test for `unsupportedUnions: 'fallback'` Kotlin shape; capture snapshot.
+7. Activate kotlinc E2E (drop ajsc Phase A gate, keep toolchain gate).
+8. `docs/codegen-kotlin.md` authored from v7 handoff + probe snapshot.
+9. CLI prints setup-guide pointer after successful Kotlin run.
+10. `CLAUDE.md` updates.
+
+The corresponding implementation plan is the next deliverable — produced from this spec via the `superpowers:writing-plans` skill, not part of this document.
+
+## Summary
+
+ajsc v7.2 made our originally-planned Kotlin codegen work simpler: `inlineTypes: true` collapses the cross-slot dedup problem by leaning on Kotlin's nested-class scoping. This polish round trims the adapter contract to v7.2's actual surface, adds two CLI flags for ajsc's escape hatches (`--kotlin-serializer`, `--unsupported-unions`), replaces the trivial test fixture with one that exercises real schema patterns, activates the previously-gated kotlinc compile E2E, and ships a downstream-consumer setup guide. Net result: the route emitter becomes a pure function, the integration tests prove real correctness, and the first Android team to integrate has a one-page guide that gets them running without backchannel questions.

package/docs/superpowers/specs/2026-04-25-swift-codegen-design.md

@@ -0,0 +1,264 @@
+# Swift Codegen Target — Design & Implementation Plan
+
+Date: 2026-04-25
+Branch: codegen-kotlin-swift
+Status: shipped
+
+## Outcome
+
+Implemented as designed: `--target swift`, `--swift-serializer`, `--swift-access-level`, full integration test against `users-golden.swift`, plus a `swiftc -parse` e2e gated by `swiftc` availability. One post-implementation deviation worth noting: the originally-spec'd files in `src/codegen/targets/swift/` were later supplemented by an extracted `src/codegen/targets/_shared/` directory of language-agnostic utilities (`path-utils`, `pick-defined`, `indent`, `pascal-case`, `route-slots`, `error-schemas`, `write-files`, `target-run`). The Swift run module (`src/codegen/targets/swift/run.ts`) and the Kotlin run module both consume `_shared/` so the dispatcher in `src/codegen/pipeline.ts` stays thin (~94 lines).
+
+## Goal
+
+Add a `--target swift` codegen target to `ts-procedures-codegen` that emits idiomatic, types-only Swift source from a `DocEnvelope`. Design mirrors the existing Kotlin target so iOS / Apple-platform consumers get parity DX with Android consumers — both targets are types-only, no runtime, no error registry, no HTTP adapter.
+
+## Non-goals
+
+- HTTP client, networking, async/await wrappers (consumers own this).
+- SSE / streams (skipped, same as Kotlin).
+- Hooks, per-call options, error dispatch logic.
+- Swift Package Manager scaffolding (consumers create `Package.swift` themselves).
+- Module declarations (Swift modules are defined by Xcode/SPM targets, not per-file like Kotlin packages).
+- ObjC interop, `@objc` annotations.
+
+## Output shape
+
+One `.swift` file per scope. Idiomatic Swift namespacing via **caseless enums** (the standard Swift idiom for namespaces — uninstantiable, zero runtime cost):
+
+```swift
+// Source hash: <md5>
+// Generated by ts-procedures-codegen — do not edit.
+import Foundation
+
+public enum Users {
+    public enum GetUser {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/{id}"
+        public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+
+        public struct PathParams: Codable {
+            public let id: String
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let name: String
+            /// ISO-8601 — set JSONDecoder.dateDecodingStrategy = .iso8601
+            public let createdAt: Date
+            public let address: Address
+
+            enum CodingKeys: String, CodingKey {
+                case id, name
+                case createdAt = "created-at"
+                case address
+            }
+
+            public struct Address: Codable {
+                public let street: String
+                public let city: String
+            }
+        }
+
+        public enum Errors {
+            public struct NotFound: Codable {
+                public let name: String
+                public let message: String
+            }
+        }
+    }
+}
+```
+
+Routes without path params get `public static let path = "/users"` (constant, not function).
+
+## CLI surface
+
+New flag: `--target swift` (extends current `'ts' | 'kotlin'` union to `'ts' | 'kotlin' | 'swift'`).
+
+Swift-specific flags:
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--swift-serializer <codable\|none>` | `codable` | Emits `: Codable`/`CodingKeys`. `none` for plain structs (consumer handles serialization). |
+| `--swift-access-level <public\|internal>` | `public` | Threads through to ajsc `accessLevel`. |
+
+Reused (apply to all targets): `--unsupported-unions`, `--array-item-naming`, `--depluralize`, `--uncountable-words`.
+
+**Important:** Unlike Kotlin, `--unsupported-unions fallback` actually works on Swift — ajsc emits a self-contained `AnyCodable` helper struct. Do NOT add the kotlin-style "no-op warning" for Swift.
+
+**No `--swift-package` flag.** Swift has no file-level package/module declaration; modules are defined by SPM/Xcode targets. This is a deliberate DX win — one fewer required arg vs Kotlin.
+
+## Config file shape
+
+```json
+{
+  "target": "swift",
+  "swift": {
+    "serializer": "codable",
+    "accessLevel": "public"
+  }
+}
+```
+
+## File layout
+
+```
+src/codegen/targets/swift/
+├── ajsc-adapter.ts             # SwiftEmitter interface + production wrapper around ajsc.emitSwift
+├── ajsc-adapter.test.ts
+├── format-swift.ts             # header, imports, indent, pickDefined helpers
+├── format-swift.test.ts
+├── emit-route-swift.ts         # per-route emitter (PathParams, Query, Body, Response, Errors)
+├── emit-route-swift.test.ts
+├── emit-scope-swift.ts         # per-scope emitter (wraps routes in nested enum namespace)
+├── emit-scope-swift.test.ts
+├── integration.test.ts         # golden-file end-to-end with stub emitter
+├── e2e-compile.test.ts         # SKIPPED by default — runs swiftc to validate generated output
+└── __fixtures__/
+    ├── users-envelope.json     # copy of kotlin fixture (same input)
+    └── users-golden.swift
+```
+
+## Architectural decisions
+
+### 1. Namespacing via caseless enums
+
+Swift idiom: `public enum Users {}` for namespace. Better than `struct Users {}` (no init, no instantiation possible, zero runtime cost). Better than nested `class` (reference type, unnecessary).
+
+### 2. Static members for path/method
+
+Inside an enum namespace, all members must be `static`. So:
+```swift
+public static let method = "GET"
+public static let pathTemplate = "/users/{id}"
+public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+```
+
+(Kotlin uses `const val` and top-level `fun`; Swift uses `public static let` and `public static func`.)
+
+### 3. ajsc options threaded
+
+Per route slot we call `emitSwift(slotSchema, { rootTypeName, inlineTypes: true, ...passthrough })`. Passthrough: `serializer`, `accessLevel`, `unsupportedUnions`, `arrayItemNaming`, `depluralize`, `uncountableWords`.
+
+`inlineTypes: true` is critical — same as Kotlin. Without it, nested object types extract to siblings and clutter the namespace.
+
+### 4. Imports merge per file
+
+ajsc returns imports per emit call (typically `["Foundation"]` only when Date/UUID/URL is in the schema). We dedupe + sort and emit once at the top of the scope file.
+
+### 5. No errors file, no index file
+
+Mirrors Kotlin: errors are nested as `enum Errors { struct NotFound: Codable { ... } }` per route. No `_errors.swift`, no barrel/index, no factories.
+
+### 6. Path interpolation
+
+Swift string interpolation is `\(expr)` (backslash + paren). Path builder template:
+```swift
+public static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+```
+
+For no-params: `public static let path = "/users"`.
+
+### 7. Source hash header
+
+`// Source hash: <md5>` as second line (after the optional `// Generated by ...` line). Same as kotlin/ts.
+
+### 8. Stream skipping
+
+Same as Kotlin — skip stream routes with a single console log per scope.
+
+### 9. Reserved word + identifier sanitization
+
+ajsc handles this via `sanitizeSwiftIdentifier` (already verified in ajsc/swift exports). Property and case names are already sanitized in ajsc's output. Our route/scope names use PascalCase already; we don't need to re-sanitize.
+
+### 10. Self-contained emitter (no extra runtime files)
+
+Like Kotlin: zero runtime files emitted. ajsc handles `AnyCodable` inline when `unsupportedUnions: 'fallback'` is set — we don't emit a separate helper file.
+
+## Pipeline integration
+
+`src/codegen/pipeline.ts` gets a third branch parallel to kotlin:
+
+```ts
+if (options.target === 'kotlin') { ... }
+if (options.target === 'swift') {
+  if (options.swiftEmitter == null) throw new Error(...)
+  // ... build errorSchemas, iterate groups, call emitSwiftScope, write files
+}
+```
+
+Naming inside `PipelineOptions`:
+- `target?: 'ts' | 'kotlin' | 'swift'`
+- `swiftSerializer?: 'codable' | 'none'`
+- `swiftAccessLevel?: 'public' | 'internal'`
+- `swiftEmitter?: SwiftEmitter` (test-injection hook, mirrors `kotlinEmitter`)
+
+Reused: `unsupportedUnions` (already on options).
+
+## CLI integration
+
+`src/codegen/bin/cli.ts`:
+
+1. Extend `target` parser to accept `'swift'`.
+2. Add flags: `--swift-serializer`, `--swift-access-level`.
+3. Add `swift?: { serializer?, accessLevel? }` to `CodegenConfig` and `ParsedArgs`.
+4. No package validation (Swift has no required field).
+5. Extend `printPostRunHints` for swift target → link `docs/codegen-swift.md`.
+6. Watch-mode: resolve swift emitter once at startup, parallel to kotlin.
+7. Do NOT add a Swift no-op-flag warning for `--unsupported-unions` (it works on Swift).
+
+## Tests
+
+Mirror the Kotlin test layout:
+
+1. **`ajsc-adapter.test.ts`** — stub creator + production resolver (mocking `ajsc` module to assert error messages when missing or `emitSwift` is undefined).
+2. **`format-swift.test.ts`** — `swiftHeader`, `swiftImports` dedupe+sort, `indent`, `pickDefined`.
+3. **`emit-route-swift.test.ts`** — path-builder for params/no-params, slot order (PathParams, Query, Body, Response), Errors namespace, stream-skipping.
+4. **`emit-scope-swift.test.ts`** — PascalCase scope name, file-name `Foo.swift`, imports dedupe across routes, empty scope, option threading.
+5. **`integration.test.ts`** — golden-file test using the `users-envelope.json` fixture and a hand-stubbed emitter, byte-identical against `users-golden.swift`.
+6. **`e2e-compile.test.ts`** — `it.skipIf(no swiftc)` — invokes `swiftc -parse` on the generated file to verify syntactic correctness. Skipped by default; only runs when `swiftc` is on `PATH`.
+
+Tests inject `createStubSwiftEmitter()` so output is deterministic and independent of ajsc's per-version evolution. The E2E compile test is the only one that exercises real ajsc.
+
+## Documentation
+
+1. **`docs/codegen-swift.md`** — full setup guide:
+   - Quickstart example
+   - SPM/Xcode integration (target setup, file inclusion)
+   - JSONDecoder configuration (`.iso8601` for Date)
+   - Sample output
+   - Discriminated unions (Swift uses `init(from:)` / `encode(to:)`)
+   - JSON-key sanitization (CodingKeys)
+   - `--swift-serializer none` (when consumers want plain structs for SwiftJSON or hand-rolled coding)
+   - Error types (nested under `Errors`)
+   - Untagged unions (`fallback` works on Swift, emits `AnyCodable`)
+   - Documented limitations
+
+2. **`CLAUDE.md`** — add Swift target paragraph parallel to Kotlin; emphasize differences (`--unsupported-unions fallback` works for Swift; no `--swift-package` requirement).
+
+3. **`agent_config/claude-code/skills/ts-procedures-swift/SKILL.md`** — parallel to `ts-procedures-kotlin/SKILL.md`. Cross-link both kotlin and swift skills from the main `ts-procedures` skill.
+
+## Implementation phases
+
+**Phase 1 (foundation):** ajsc-adapter, format helpers, emit-route, emit-scope (+ unit tests for each). Single sub-agent.
+
+**Phase 2 (integration):** Wire into pipeline.ts, index.ts, cli.ts. Add integration test with golden file. Single sub-agent depending on Phase 1.
+
+**Phase 3 (docs+skill, parallel with Phase 1/2):** Write `docs/codegen-swift.md`, update CLAUDE.md, create agent_config skill. Single sub-agent independent of code.
+
+**Phase 4 (verify):** `npm run build && npm test && npm run lint`. Inspect generated golden file. Confirm CLI invocation works.
+
+## Risk / open questions
+
+- **swiftc on dev machines** — E2E test is skipped by default to avoid CI failures. Same pattern as kotlin's `e2e-compile.test.ts`.
+- **`type: integer` → `Int64`** — Swift idiom is `Int` for general use; `Int64` is heavier visually. Accept ajsc's choice for now (can revisit if mobile devs request `Int`).
+- **`type: number` → `Double`** — for monetary values, mobile devs should use `Decimal`. Document the workaround in `docs/codegen-swift.md`.
+- **CodingKeys are mandatory** when keys differ — ajsc emits these automatically. We just have to make sure our golden file includes them and tests don't lock them away.
+
+## Success criteria
+
+- `npm test` passes (all kotlin tests still pass, new swift tests pass).
+- `npm run build` succeeds.
+- `npm run lint` clean.
+- Manual run: `npx ts-procedures-codegen --target swift --url ... --out ...` produces a valid `Users.swift` (or whatever scope) that compiles with `swiftc -parse`.
+- Docs and skill files committed; `agent_config/postinstall` will distribute them on next install.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "6.0.2",
+  "version": "6.2.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",
@@ -78,7 +78,7 @@
     "framework"
   ],
   "optionalDependencies": {
-    "ajsc": "^5.2.4",
+    "ajsc": "7.2.0",
     "express": "^5.2.1",
     "hono": "^4.7.4"
   },