ts-procedures 6.0.1 → 6.1.0

package/build/codegen/targets/kotlin/format-kotlin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-kotlin.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/format-kotlin.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,WAAW,GAAG,EAAE,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,mBAAmB,IAAI,EAAE,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAiB;IAC7C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAClD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,KAAa;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACnC,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC;SAC9D,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,GAAM,EACN,IAAkB;IAElB,MAAM,GAAG,GAAwB,EAAE,CAAA;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAA;QACtB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;QAClB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/build/codegen/targets/kotlin/format-kotlin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/codegen/targets/kotlin/format-kotlin.test.js

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports, indent, pickDefined, } from './format-kotlin.js';
+describe('format-kotlin', () => {
+    it('emits a package declaration', () => {
+        expect(kotlinPackageDecl('com.example.api')).toBe('package com.example.api');
+    });
+    it('emits a source-hash header line', () => {
+        expect(kotlinSourceHashHeader('abc123')).toBe('// Source hash: abc123');
+    });
+    it('dedupes and sorts imports', () => {
+        expect(kotlinImports(['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Serializable'])).toBe('import kotlinx.serialization.SerialName\nimport kotlinx.serialization.Serializable');
+    });
+    it('returns empty string when no imports', () => {
+        expect(kotlinImports([])).toBe('');
+    });
+    it('indents every line by 4 spaces per level', () => {
+        expect(indent('a\nb', 1)).toBe('    a\n    b');
+        expect(indent('a', 2)).toBe('        a');
+    });
+    it('preserves blank lines without trailing whitespace when indenting', () => {
+        expect(indent('a\n\nb', 1)).toBe('    a\n\n    b');
+    });
+});
+describe('pickDefined', () => {
+    it('returns only the keys whose values are not undefined', () => {
+        expect(pickDefined({ a: 1, b: undefined, c: 3 }, ['a', 'b', 'c']))
+            .toEqual({ a: 1, c: 3 });
+    });
+    it('preserves the literal `false` value for boolean opts', () => {
+        expect(pickDefined({ depluralize: false, x: undefined }, ['depluralize', 'x']))
+            .toEqual({ depluralize: false });
+    });
+    it('preserves the literal `false` for `string | false` opts (e.g. arrayItemNaming)', () => {
+        const result = pickDefined({ arrayItemNaming: false }, ['arrayItemNaming']);
+        expect(result).toEqual({ arrayItemNaming: false });
+        expect('arrayItemNaming' in result).toBe(true);
+    });
+    it('omits keys not in the keys list even if they are defined on src', () => {
+        expect(pickDefined({ a: 1, b: 2 }, ['a']))
+            .toEqual({ a: 1 });
+    });
+    it('returns an empty object when all keys are undefined', () => {
+        expect(pickDefined({ a: undefined, b: undefined }, ['a', 'b']))
+            .toEqual({});
+    });
+    it('returns an empty object when keys is empty', () => {
+        expect(pickDefined({ a: 1 }, [])).toEqual({});
+    });
+});
+//# sourceMappingURL=format-kotlin.test.js.map

package/build/codegen/targets/kotlin/format-kotlin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-kotlin.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/format-kotlin.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,MAAM,EACN,WAAW,GACZ,MAAM,oBAAoB,CAAA;AAE3B,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAA;IAC9E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAA;IACzE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,aAAa,CAAC,CAAC,oCAAoC,EAAE,kCAAkC,EAAE,oCAAoC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC1I,oFAAoF,CACrF,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAC9C,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;IACpD,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAA4C,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;aACzG,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IAC5B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAA2C,EAAE,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,CAAC;aACrH,OAAO,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gFAAgF,EAAE,GAAG,EAAE;QAExF,MAAM,MAAM,GAAG,WAAW,CAAmB,EAAE,eAAe,EAAE,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAA;QAC7F,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAA;QAClD,MAAM,CAAC,iBAAiB,IAAI,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAgC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;aACrE,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;IACtB,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAgC,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;aAC1F,OAAO,CAAC,EAAE,CAAC,CAAA;IAChB,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAa,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC1D,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/codegen/targets/kotlin/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/codegen/targets/kotlin/integration.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runPipeline } from '../../pipeline.js';
+import { assertGoldenOrUpdate } from '../../test-helpers/golden.js';
+import { createStubKotlinEmitter } from './ajsc-adapter.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ok = (code, rootTypeName, imports = ['kotlinx.serialization.Serializable']) => ({
+    code,
+    rootTypeName,
+    extractedTypeNames: [],
+    imports,
+});
+describe('kotlin codegen — integration', () => {
+    it('produces byte-identical output against the golden fixture', async () => {
+        const envelopePath = join(__dirname, '__fixtures__/users-envelope.json');
+        const goldenPath = join(__dirname, '__fixtures__/users-golden.kt');
+        const envelope = JSON.parse(await readFile(envelopePath, 'utf8'));
+        // Hand-authored slot outputs in the v7.2 nested-class shape (inlineTypes: true).
+        //
+        // The stub map is keyed on rootTypeName, NOT on (route, slot). Both GetUser
+        // and CreateUser have a slot named "Response" — they intentionally share the
+        // single stub entry below. The golden file therefore shows three identical
+        // Response data classes (one per route that has one). This is correct: the
+        // integration test pins our file-assembly logic, not real ajsc per-route
+        // output. The kotlinc E2E (Task 11) exercises real ajsc against the same
+        // fixture and would surface any incompatibility.
+        const emitter = createStubKotlinEmitter({
+            // GetUser
+            PathParams: ok('@Serializable\ndata class PathParams(\n    val id: String,\n)', 'PathParams'),
+            Response: ok('@Serializable\ndata class Response(\n    val id: String,\n    val name: String,\n    @SerialName("created-at") @Contextual val createdAt: java.time.Instant,\n    val address: Address,\n) {\n    @Serializable\n    data class Address(\n        val street: String,\n        val city: String,\n    )\n}', 'Response', ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Contextual']),
+            NotFound: ok('@Serializable\ndata class NotFound(\n    val name: String = "NotFound",\n    val message: String,\n)', 'NotFound'),
+            // CreateUser
+            Body: ok('@Serializable\n@JsonClassDiscriminator("kind")\nsealed interface Body {\n    @Serializable\n    @SerialName("guest")\n    data class GuestBody(\n        val displayName: String,\n    ) : Body\n\n    @Serializable\n    @SerialName("registered")\n    data class RegisteredBody(\n        val email: String,\n        val name: String,\n    ) : Body\n}', 'Body', ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.json.JsonClassDiscriminator']),
+            ValidationError: ok('@Serializable\ndata class ValidationError(\n    val name: String = "ValidationError",\n    val message: String,\n    val field: String? = null,\n)', 'ValidationError'),
+            // ListUsers
+            Query: ok('@Serializable\ndata class Query(\n    val status: Status? = null,\n    val limit: Long? = null,\n) {\n    @Serializable\n    enum class Status {\n        @SerialName("active") ACTIVE,\n        @SerialName("inactive") INACTIVE,\n    }\n}', 'Query', ['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName']),
+        });
+        const files = await runPipeline({
+            envelope, outDir: 'out', dryRun: true,
+            target: 'kotlin', kotlinPackage: 'com.example.api',
+            kotlinEmitter: emitter,
+        });
+        expect(files).toHaveLength(1);
+        expect(files[0].path).toBe(join('out', 'Users.kt'));
+        await assertGoldenOrUpdate(files[0].code, goldenPath);
+    });
+});
+//# sourceMappingURL=integration.test.js.map

package/build/codegen/targets/kotlin/integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/integration.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AACnE,OAAO,EAAE,uBAAuB,EAAyB,MAAM,mBAAmB,CAAA;AAElF,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAErC,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,YAAoB,EAAE,UAAoB,CAAC,oCAAoC,CAAC,EAAoB,EAAE,CAAC,CAAC;IAChI,IAAI;IACJ,YAAY;IACZ,kBAAkB,EAAE,EAAE;IACtB,OAAO;CACR,CAAC,CAAA;AAEF,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,kCAAkC,CAAC,CAAA;QACxE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,CAAA;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;QAEjE,iFAAiF;QACjF,EAAE;QACF,4EAA4E;QAC5E,6EAA6E;QAC7E,2EAA2E;QAC3E,2EAA2E;QAC3E,yEAAyE;QACzE,yEAAyE;QACzE,iDAAiD;QACjD,MAAM,OAAO,GAAG,uBAAuB,CAAC;YACtC,UAAU;YACV,UAAU,EAAE,EAAE,CAAC,+DAA+D,EAAE,YAAY,CAAC;YAC7F,QAAQ,EAAE,EAAE,CACV,4SAA4S,EAC5S,UAAU,EACV,CAAC,oCAAoC,EAAE,kCAAkC,EAAE,kCAAkC,CAAC,CAC/G;YACD,QAAQ,EAAE,EAAE,CACV,sGAAsG,EACtG,UAAU,CACX;YAED,aAAa;YACb,IAAI,EAAE,EAAE,CACN,6VAA6V,EAC7V,MAAM,EACN,CAAC,oCAAoC,EAAE,kCAAkC,EAAE,mDAAmD,CAAC,CAChI;YACD,eAAe,EAAE,EAAE,CACjB,oJAAoJ,EACpJ,iBAAiB,CAClB;YAED,YAAY;YACZ,KAAK,EAAE,EAAE,CACP,8OAA8O,EAC9O,OAAO,EACP,CAAC,oCAAoC,EAAE,kCAAkC,CAAC,CAC3E;SACF,CAAC,CAAA;QAEF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC;YAC9B,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI;YACrC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB;YAClD,aAAa,EAAE,OAAO;SACvB,CAAC,CAAA;QAEF,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;QAC7B,MAAM,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAA;QAEpD,MAAM,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACxD,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/codegen/targets/kotlin/probe-unsupported-unions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/codegen/targets/kotlin/probe-unsupported-unions.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+let ajscResolvable = false;
+let emitKotlinFn;
+try {
+    const ajsc = await import('ajsc');
+    if (typeof ajsc.emitKotlin === 'function') {
+        ajscResolvable = true;
+        emitKotlinFn = ajsc.emitKotlin;
+    }
+}
+catch {
+    // ajsc not installed (e.g. npm install --omit=optional); test skips below.
+}
+describe('ajsc.emitKotlin — untagged oneOf behavior', () => {
+    it.skipIf(!ajscResolvable)('produces a deterministic fallback shape for an untagged oneOf', () => {
+        const schema = {
+            oneOf: [{ type: 'string' }, { type: 'integer' }],
+        };
+        const result = emitKotlinFn(schema, {
+            rootTypeName: 'Mixed',
+            inlineTypes: true,
+            unsupportedUnions: 'fallback',
+        });
+        // Snapshot pins the current ajsc behavior. If ajsc changes the fallback
+        // shape, this diff prompts an intentional review and a corresponding
+        // update to docs/codegen-kotlin.md.
+        expect({
+            code: result.code,
+            imports: result.imports.slice().sort(),
+            rootTypeName: result.rootTypeName,
+            extractedTypeNames: result.extractedTypeNames.slice().sort(),
+        }).toMatchSnapshot();
+    });
+    // Companion to test 1: confirms 'fallback' is not load-bearing — ajsc emits the
+    // same shape with or without it. If these snapshots ever diverge, that's a
+    // meaningful behavior change worth surfacing in docs/codegen-kotlin.md.
+    it.skipIf(!ajscResolvable)('silently falls back to empty data class when unsupportedUnions is not specified', () => {
+        const schema = { oneOf: [{ type: 'string' }, { type: 'integer' }] };
+        const result = emitKotlinFn(schema, { rootTypeName: 'Mixed', inlineTypes: true });
+        // When unsupportedUnions defaults (not explicitly set), ajsc does NOT throw.
+        // Instead it silently emits an empty data class.
+        expect({
+            code: result.code,
+            imports: result.imports.slice().sort(),
+            rootTypeName: result.rootTypeName,
+            extractedTypeNames: result.extractedTypeNames.slice().sort(),
+        }).toMatchSnapshot();
+    });
+});
+//# sourceMappingURL=probe-unsupported-unions.test.js.map

package/build/codegen/targets/kotlin/probe-unsupported-unions.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-unsupported-unions.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/probe-unsupported-unions.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE7C,IAAI,cAAc,GAAG,KAAK,CAAA;AAC1B,IAAI,YAKS,CAAA;AAEb,IAAI,CAAC;IACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAA;IACjC,IAAI,OAAQ,IAAiC,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QACxE,cAAc,GAAG,IAAI,CAAA;QACrB,YAAY,GAAI,IAA4C,CAAC,UAAW,CAAA;IAC1E,CAAC;AACH,CAAC;AAAC,MAAM,CAAC;IACP,2EAA2E;AAC7E,CAAC;AAED,QAAQ,CAAC,2CAA2C,EAAE,GAAG,EAAE;IACzD,EAAE,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CACxB,+DAA+D,EAC/D,GAAG,EAAE;QACH,MAAM,MAAM,GAAG;YACb,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;SACjD,CAAA;QACD,MAAM,MAAM,GAAG,YAAa,CAAC,MAAM,EAAE;YACnC,YAAY,EAAE,OAAO;YACrB,WAAW,EAAE,IAAI;YACjB,iBAAiB,EAAE,UAAU;SAC9B,CAAC,CAAA;QAEF,wEAAwE;QACxE,qEAAqE;QACrE,oCAAoC;QACpC,MAAM,CAAC;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE;YACtC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE;SAC7D,CAAC,CAAC,eAAe,EAAE,CAAA;IACtB,CAAC,CACF,CAAA;IAED,gFAAgF;IAChF,2EAA2E;IAC3E,wEAAwE;IACxE,EAAE,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CACxB,iFAAiF,EACjF,GAAG,EAAE;QACH,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAA;QACnE,MAAM,MAAM,GAAG,YAAa,CAAC,MAAM,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAA;QAClF,6EAA6E;QAC7E,iDAAiD;QACjD,MAAM,CAAC;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE;YACtC,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE;SAC7D,CAAC,CAAC,eAAe,EAAE,CAAA;IACtB,CAAC,CACF,CAAA;AACH,CAAC,CAAC,CAAA"}

package/build/codegen/test-helpers/golden.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Compares produced source against a golden file, with optional regeneration.
+ *
+ * - Normal mode: reads `goldenPath`, splices the produced source-hash line into
+ *   the golden's `<PLACEHOLDER>` slot, and asserts byte-equality.
+ * - Regen mode (`UPDATE_GOLDENS=1`): replaces the produced source-hash line with
+ *   `<PLACEHOLDER>` and writes the result to `goldenPath`. The next normal run
+ *   will assert against the new golden.
+ *
+ * The source-hash placeholder lets us check generated content into source
+ * control without coupling the golden to a specific envelope hash. Codegen
+ * outputs that don't include a `// Source hash:` line work too — the
+ * splice/replace is a no-op when no match is found.
+ */
+export declare function assertGoldenOrUpdate(produced: string, goldenPath: string): Promise<void>;

package/build/codegen/test-helpers/golden.js

@@ -0,0 +1,30 @@
+import { expect } from 'vitest';
+import { readFile, writeFile } from 'node:fs/promises';
+/**
+ * Compares produced source against a golden file, with optional regeneration.
+ *
+ * - Normal mode: reads `goldenPath`, splices the produced source-hash line into
+ *   the golden's `<PLACEHOLDER>` slot, and asserts byte-equality.
+ * - Regen mode (`UPDATE_GOLDENS=1`): replaces the produced source-hash line with
+ *   `<PLACEHOLDER>` and writes the result to `goldenPath`. The next normal run
+ *   will assert against the new golden.
+ *
+ * The source-hash placeholder lets us check generated content into source
+ * control without coupling the golden to a specific envelope hash. Codegen
+ * outputs that don't include a `// Source hash:` line work too — the
+ * splice/replace is a no-op when no match is found.
+ */
+export async function assertGoldenOrUpdate(produced, goldenPath) {
+    if (process.env.UPDATE_GOLDENS === '1') {
+        const goldenContent = produced.replace(/^\/\/ Source hash: [a-f0-9]+$/m, '// Source hash: <PLACEHOLDER>');
+        await writeFile(goldenPath, goldenContent, 'utf-8');
+        // eslint-disable-next-line no-console
+        console.log(`[golden-test] Wrote golden: ${goldenPath}`);
+        return;
+    }
+    const goldenTemplate = await readFile(goldenPath, 'utf8');
+    const sourceHashLine = produced.split('\n').find((l) => l.startsWith('// Source hash:')) ?? '';
+    const goldenWithHash = goldenTemplate.replace('// Source hash: <PLACEHOLDER>', sourceHashLine);
+    expect(produced).toBe(goldenWithHash);
+}
+//# sourceMappingURL=golden.js.map

package/build/codegen/test-helpers/golden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden.js","sourceRoot":"","sources":["../../../src/codegen/test-helpers/golden.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEtD;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,QAAgB,EAAE,UAAkB;IAC7E,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,GAAG,EAAE,CAAC;QACvC,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CACpC,gCAAgC,EAChC,+BAA+B,CAChC,CAAA;QACD,MAAM,SAAS,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,CAAC,CAAA;QACnD,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,+BAA+B,UAAU,EAAE,CAAC,CAAA;QACxD,OAAM;IACR,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IACzD,MAAM,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,IAAI,EAAE,CAAA;IAC9F,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,CAAC,+BAA+B,EAAE,cAAc,CAAC,CAAA;IAC9F,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;AACvC,CAAC"}

package/build/codegen/test-helpers/golden.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/codegen/test-helpers/golden.test.js

@@ -0,0 +1,76 @@
+import { describe, expect, it, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { assertGoldenOrUpdate } from './golden.js';
+let tmpDir;
+afterEach(() => {
+    if (tmpDir != null) {
+        rmSync(tmpDir, { recursive: true, force: true });
+        tmpDir = undefined;
+    }
+});
+function makeTmp() {
+    tmpDir = mkdtempSync(join(tmpdir(), 'tsp-golden-'));
+    return tmpDir;
+}
+describe('assertGoldenOrUpdate', () => {
+    it('asserts byte-equality against golden when produced matches (with hash splice)', async () => {
+        const dir = makeTmp();
+        const goldenPath = join(dir, 'expected.txt');
+        writeFileSync(goldenPath, 'hello\n// Source hash: <PLACEHOLDER>\nworld\n', 'utf-8');
+        const produced = 'hello\n// Source hash: abc123def456\nworld\n';
+        await expect(assertGoldenOrUpdate(produced, goldenPath)).resolves.toBeUndefined();
+    });
+    it('throws when produced does not match golden', async () => {
+        const dir = makeTmp();
+        const goldenPath = join(dir, 'expected.txt');
+        writeFileSync(goldenPath, 'expected content\n', 'utf-8');
+        const produced = 'different content\n';
+        await expect(assertGoldenOrUpdate(produced, goldenPath)).rejects.toThrow();
+    });
+    it('writes a portable golden when UPDATE_GOLDENS=1', async () => {
+        const original = process.env.UPDATE_GOLDENS;
+        process.env.UPDATE_GOLDENS = '1';
+        try {
+            const dir = makeTmp();
+            const goldenPath = join(dir, 'expected.txt');
+            const produced = 'hello\n// Source hash: deadbeef1234\nworld\n';
+            await assertGoldenOrUpdate(produced, goldenPath);
+            const written = readFileSync(goldenPath, 'utf-8');
+            expect(written).toBe('hello\n// Source hash: <PLACEHOLDER>\nworld\n');
+        }
+        finally {
+            if (original === undefined)
+                delete process.env.UPDATE_GOLDENS;
+            else
+                process.env.UPDATE_GOLDENS = original;
+        }
+    });
+    it('handles produced output without a source-hash line', async () => {
+        const dir = makeTmp();
+        const goldenPath = join(dir, 'expected.txt');
+        writeFileSync(goldenPath, 'plain content\n', 'utf-8');
+        // No source hash; splice is a no-op on both sides.
+        await expect(assertGoldenOrUpdate('plain content\n', goldenPath)).resolves.toBeUndefined();
+    });
+    it('regenerate mode handles produced output without a source-hash line', async () => {
+        const original = process.env.UPDATE_GOLDENS;
+        process.env.UPDATE_GOLDENS = '1';
+        try {
+            const dir = makeTmp();
+            const goldenPath = join(dir, 'expected.txt');
+            const produced = 'no hash line here\n';
+            await assertGoldenOrUpdate(produced, goldenPath);
+            const written = readFileSync(goldenPath, 'utf-8');
+            expect(written).toBe('no hash line here\n');
+        }
+        finally {
+            if (original === undefined)
+                delete process.env.UPDATE_GOLDENS;
+            else
+                process.env.UPDATE_GOLDENS = original;
+        }
+    });
+});
+//# sourceMappingURL=golden.test.js.map

package/build/codegen/test-helpers/golden.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"golden.test.js","sourceRoot":"","sources":["../../../src/codegen/test-helpers/golden.test.ts"],"names":[],"mappings":"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"}

package/docs/codegen-kotlin.md

@@ -0,0 +1,175 @@
+# Kotlin Codegen Setup Guide
+
+Generated by `ts-procedures-codegen --target kotlin`. One `.kt` file per scope; types are nested under route objects (`Users.GetUser.Response`, `Users.GetUser.Body.Address`).
+
+## Quickstart
+
+```bash
+npx ts-procedures-codegen \
+  --target kotlin \
+  --kotlin-package com.example.api \
+  --url https://api.example.com/_ts-procedures.json \
+  --out ./src/main/kotlin/com/example/api
+```
+
+Each scope produces one file (e.g. `Users.kt`). Access generated types as `Users.GetUser.Response`, `Users.GetUser.Body.GuestBody`, `Users.GetUser.Errors.NotFound`.
+
+## Gradle setup
+
+The default `--kotlin-serializer kotlinx` mode emits `@Serializable` data classes. Add the kotlinx-serialization plugin and runtime:
+
+```kotlin
+// build.gradle.kts
+plugins {
+    kotlin("jvm") version "<your-kotlin-version>"
+    kotlin("plugin.serialization") version "<your-kotlin-version>"
+}
+
+dependencies {
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:<version>")
+}
+```
+
+(`kotlinx-serialization-core` is a transitive dependency of `-json`; you don't need to declare it explicitly.)
+
+**JVM only.** Kotlin Multiplatform is not yet supported. If you need KMP-portable types, fall back to `--kotlin-serializer none` or post-process the emitted code.
+
+## Contextual serializers
+
+`format: date-time`, `format: uuid`, `format: uri`, `format: date`, `format: time` map to JVM stdlib types (`java.time.Instant`, `java.util.UUID`, etc.) annotated with `@Contextual`. Kotlinx-serialization does not know how to serialize these natively — register contextual serializers in your `Json` configuration:
+
+```kotlin
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.modules.SerializersModule
+import kotlinx.serialization.modules.contextual
+
+val json = Json {
+    serializersModule = SerializersModule {
+        contextual(java.time.Instant::class, InstantSerializer)
+        contextual(java.util.UUID::class, UUIDSerializer)
+        contextual(java.net.URI::class, URISerializer)
+        // ...etc for any format you use
+    }
+}
+```
+
+The serializers themselves are your responsibility (we don't ship them — the choice between ISO-8601 strings, epoch milliseconds, etc. is application-specific). Public Gist-quality implementations are widely available; we recommend ISO-8601 to match the server.
+
+## Discriminated unions
+
+A schema with a `oneOf` whose variants share a const-valued discriminator (e.g. `kind: "guest" | "registered"`) emits as a sealed interface:
+
+```kotlin
+@Serializable
+@JsonClassDiscriminator("kind")
+sealed interface Body {
+    @Serializable
+    @SerialName("guest")
+    data class GuestBody(val displayName: String) : Body
+
+    @Serializable
+    @SerialName("registered")
+    data class RegisteredBody(val email: String, val name: String) : Body
+}
+```
+
+The discriminator field (`kind`) is **erased** from each variant under `--kotlin-serializer kotlinx` — `@SerialName` carries it on the wire. With `--kotlin-serializer none` the discriminator field is retained.
+
+`@JsonClassDiscriminator` is read automatically by the kotlinx `Json` instance — no extra config needed.
+
+## JSON-key sanitization
+
+Kebab-case and snake-case JSON keys become camelCase property names with `@SerialName` auto-emitted so the wire format stays correct:
+
+```kotlin
+@Serializable
+data class Response(
+    @SerialName("created-at")
+    @Contextual
+    val createdAt: java.time.Instant,
+)
+```
+
+Reserved Kotlin words get a trailing underscore (`class` → `class_`).
+
+## Switching off kotlinx (Moshi, Gson, hand-written)
+
+`--kotlin-serializer none` emits plain `data class` types with no `@Serializable` annotation. You're then responsible for adapter setup:
+
+- **Reflection-based libraries** (Gson) work without further changes.
+- **Codegen-based** (Moshi with codegen) need their own annotation layer added.
+- Sealed interfaces still emit; the discriminator field is **retained** in variants under `none` mode.
+
+## Error types
+
+Each route that declares errors gets a nested `Errors` object containing one `@Serializable data class` per error name:
+
+```kotlin
+object Users {
+    object GetUser {
+        // ... method, path, types ...
+        object Errors {
+            @Serializable
+            data class NotFound(
+                val name: String = "NotFound",
+                val message: String,
+            )
+        }
+    }
+}
+```
+
+Access generated error types as `Users.GetUser.Errors.NotFound`.
+
+**No runtime dispatch.** Unlike the TypeScript target, the Kotlin target ships **types only** — there is no error registry, no `instanceof`-style lookup, no `dispatchTypedError`. Mobile consumers catch HTTP failures themselves and inspect `body.name` (which is a regular `String` field, not a type-system discriminator) to decide which error data class to deserialize against:
+
+```kotlin
+suspend fun loadUser(id: String): Result<Users.GetUser.Response> {
+    val response = httpClient.request(method = Users.GetUser.method, path = "...")
+    return when {
+        response.status == 200 -> Result.success(json.decodeFromString(response.body))
+        response.status == 404 -> {
+            val err = json.decodeFromString<Users.GetUser.Errors.NotFound>(response.body)
+            Result.failure(NotFoundException(err.message))
+        }
+        else -> Result.failure(IOException("HTTP ${response.status}"))
+    }
+}
+```
+
+Choosing the dispatch strategy (status-code based, body.name based, sealed-class hierarchy of your own, etc.) is intentionally left to consumers.
+
+## Untagged unions
+
+ajsc v7.2's Kotlin emitter silently produces an empty `@Serializable data class` for any untagged `oneOf` schema, regardless of whether `--unsupported-unions fallback` is set. There is no "throws on default" mode for Kotlin (that's Swift behavior). The `--unsupported-unions` flag is currently a no-op for the Kotlin target.
+
+For example, the schema `oneOf: [{ type: 'string' }, { type: 'integer' }]` with `rootTypeName: 'Mixed'` produces:
+
+```kotlin
+@Serializable
+data class Mixed()
+```
+
+Imports: `kotlinx.serialization.Serializable`.
+
+**Practical implication.** This empty data class won't round-trip your data — calling `Json.decodeFromString<Mixed>("\"hello\"")` will fail because `Mixed` has no payload. **Untagged unions in your schema cannot be consumed via the generated Kotlin types.** Workarounds:
+
+1. **Add a discriminator** to your server-side schema so it becomes a tagged union (sealed interface emission — see "Discriminated unions" section above).
+2. **Hand-write a `KSerializer<T>` `companion object`** in a sibling file that resolves the union at deserialization time.
+3. **Strip the union field at the codegen boundary** — pre-process the envelope to replace untagged `oneOf` with a single permissive type (e.g. `JsonElement`).
+
+We track this as an ajsc upstream limitation; if it's resolved in a future ajsc release, this section will be updated.
+
+## Documented limitations
+
+The following ajsc behaviors are intentional and documented; they are **not bugs**:
+
+- `additionalProperties: { type: T }` is silently dropped with a `/** Note: schema permits additional keys of type T — not modeled. */` KDoc note. If your contract uses extra keys, add a sibling `Map<String, T>` field by hand or write a custom `KSerializer`.
+- Tuples with 4 or more positional types throw (`Pair`/`Triple` only). Refactor to a struct schema upstream.
+- Schema-level `examples` and `not` / `patternProperties` are not modeled (the latter throw with a path-bearing error).
+
+## Reference
+
+- Spec: [`docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md`](./superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md)
+- ajsc README: `node_modules/ajsc/README.md` (or [npmjs.com/package/ajsc](https://www.npmjs.com/package/ajsc))
+- ts-procedures-codegen CLI flags: see `CLAUDE.md` (search for "Kotlin target") and the spec linked above. (`--help` is not currently implemented; pass invalid/missing args to see error messages with usage hints.)

package/docs/http-integrations.md

@@ -271,6 +271,38 @@ The observer is awaited before the response is sent, and any error it throws is
 
 Configuring only the taxonomy, only `onError`, both, or neither are all valid. When neither is configured the builder goes straight from step 1 to step 4.
 
+## One Hono Server, Multiple Builders
+
+You don't need a separate Hono instance per builder. `HonoRPCAppBuilder`, `HonoAPIAppBuilder`, and `HonoStreamAppBuilder` each accept an optional `app?: Hono` in their config — pass the same instance and they all mount their routes onto the same server:
+
+```typescript
+import { Hono } from 'hono'
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { HonoStreamAppBuilder } from 'ts-procedures/hono-stream'
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const app = new Hono()
+
+const rpcBuilder = new HonoRPCAppBuilder({ app, pathPrefix: '/rpc' })
+  .register(RPC, ctxResolver)
+const apiBuilder = new HonoAPIAppBuilder({ app, pathPrefix: '/api' })
+  .register(API, ctxResolver)
+const streamBuilder = new HonoStreamAppBuilder({ app })
+  .register(Stream, ctxResolver)
+
+rpcBuilder.build()
+apiBuilder.build()
+streamBuilder.build()
+
+const docs = new DocRegistry().from(rpcBuilder).from(apiBuilder).from(streamBuilder)
+app.get('/docs', (c) => c.json(docs.toJSON()))
+```
+
+One server, one Hono instance, one `/docs` endpoint. The three builders are **registration scopes**, not separate servers — each owns the routes it mounts (RPC vs API vs Stream) but all of them coexist on the same listener. Mix in custom middleware (`app.use(...)`), health checks, or static routes on the shared `app` before or after `.build()`.
+
+If you omit `app`, each builder constructs its own internal `Hono` instance — useful when you really do want isolated apps (multi-tenant routing, separate ports, etc.).
+
 ## DocRegistry — Composing Docs from Multiple Builders
 
 Use `DocRegistry` to compose route documentation from any combination of HTTP builders into a typed envelope: