Emit TypeScript transfer type converters and operation type info

[bergundy]

Nine commits, best reviewed one at a time. The headline is the TypeScript output: a model's companion becomes a TransferTypeConverter instance, and every generated operation carries the converter for each non-void side, so a protocol integration can apply the conversion without the caller wiring it by hand. Behind it, three fixes to the emitted-name layer — it had to learn the new identifiers, and teaching it surfaced two pre-existing holes — and then three more on multi-input correctness, where checking that the new converter identifiers were scoped properly turned up naming and file-layout bugs that emit code the target's own compiler rejects.

The first commit, 85a8ba1 ("Reject a root type name that collides with a $defs name"), is separate self-contained work that was sitting on local main unpushed; it rides along here rather than being split out. Review starts at 3d12399.

TypeScript: mappers become transfer type converters

Implements the contract from nexus-rpc/sdk-typescript#40.

// before
export class UserMapper {
  fromIntermediate(value: unknown): User { … }
  toIntermediate(value: User): unknown { … }
}
new UserMapper().fromIntermediate(raw)

// after
export const userTransferTypeConverter = new class implements TransferTypeConverter<User> {
  fromTransferType(value: unknown): User { … }
  toTransferType(value: User): unknown { … }
}()
userTransferTypeConverter.fromTransferType(raw)

Method bodies are unchanged: TransferTypeConverter<T> defaults its transfer type to unknown, which already matched the emitted signatures. models.ts gains a type-only import type { TransferTypeConverter } from "nexus-rpc".

The identifier is the model's resolved type identifier lower-camel-cased, read back through the name manifest wherever a reference is emitted — the plan hands operations their own type copies, which carry the derived name, not the resolved one — so an x-ts-name override moves the type, its converter, and the operation that names them, together.

Two consequences for load-time naming, both of which used to be silent bad output:

• TransferTypeConverter is now imported into every models.ts, so it joins TypeScript's reserved runtime identifiers: a $defs type of that name rejects at load with a fix-it instead of emitting an import/local conflict.
• The derived converter identifiers enter the per-module P15 namespace, because lower-camel-casing folds names the type namespace keeps apart — HTTPError and HttpError both yield httpErrorTransferTypeConverter. A fold, or a service whose x-ts-name lands on a converter name, is a P15 load reject instead of a module that declares one const twice. The parser owns the derivation, as it owns the rest of the per-language naming policy, so the collision pass and the emitters cannot drift apart.

Operation type info

Each non-void side of nexus.operation now carries inputType/outputType = { transferTypeConverter: … } naming the I/O model's converter. A void side carries neither field: there is no value to convert, and an empty TypeInfo would assert a conversion that does not exist. Cross-module I/O imports the converter as a value from its declaring module.

JSON-Schema input only — the WIT tier has no converters and its output is byte-identical.

The nexus-rpc shim

The published nexus-rpc 0.0.2 predates the type-info API, and upstream has no prepare script, so a git dependency installs unbuilt. Runtime is unaffected (operation() spreads its options through untouched), so both sample projects carry a types-only augmentation under shims/ to bridge typechecking until the release lands. It comes out when that release ships.

Emitted-name fixes

• A model's x-<lang>-name override was invisible to every other input file that referenced it, in all four languages. Each leaf built its manifest from its own declarations only, so a consuming module emitted the pre-override identifier: a dangling operation generic, model import and converter import, a dangling field type for a cross-file $ref property, and — in Go's flat package — a reference to a type name that is never declared. EmittedNameResolutionPass now builds one manifest over the whole tree and rewrites every emitted name from it, references included (routed through ApiSpec::map_names, so operation I/O and record field types are reached). Collision scoping is untouched: build_name_manifest groups by module key, so a foreign model never joins a local module's namespace. Cross-module $refs inside a model's schema are resolved by the backends, which see one leaf at a time, so the pass records the foreign identifiers on PlannedSpecData::cross_module_model_names and each backend seeds its $ref registry with them — replacing the Go backend's approximation, which keyed entries by the pre-override name.
• An x-<lang>-name on a property did not move two identifiers synthesized from it, so a collision on either was rejected with a fix-it the author could not act on. TypeScript's DEFAULT_<FIELD> and Go's closed-value type <Type><Field> derived from the JSON key rather than the emitted member identifier: retryCount and retry_count collide on DEFAULT_RETRY_COUNT, and the rejection's own remedy moved the members apart while leaving both constants on the colliding name — the only escape left was renaming the JSON property, i.e. changing the wire contract. Both now derive from the emitted member identifier, in the emitters and in the manifest that predicts them, which also puts Go's synthesized type name in agreement with Java's nested value class. The governing rule — a name synthesized from a member moves with that member; a name synthesized from a position stays with the position — now sits in PRINCIPLES §15, which previously claimed the override moved every name synthesized from the property.
• TypeScript's <FIELD>_CONST bindings never entered the P15 namespace, so two could coincide and both be emitted. They coincide through the model-name disambiguator: A.kind is prefixed because kind is not unique, giving A_KIND_CONST, which is exactly what a unique C.aKind produces unprefixed — const A_KIND_CONST twice in one models.ts, a TypeScript SyntaxError emitted without a diagnostic. Now a reject with a fix-it naming both origins. (default.md and const.md both claimed TypeScript synthesizes no identifier for a const; it synthesizes no named type, but it does emit this value binding, and both now say so.)

Generated samples move only where the TypeScript converters do: no checked-in schema puts a name override on a cross-file model, or on a default- or const-bearing property.

Multi-input correctness

Three later commits, all about generating from a directory of schema files rather than a single file. They surfaced while checking that the new converter identifiers were scoped correctly, and each one turned out to be a pre-existing hole that produces code the target's own compiler rejects. No checked-in sample changes for any of them — see the end of this section for why that is expected rather than reassuring.

0b9ba68 — collision scope per target

Two scope errors, plus a third found while fixing them:

• Services never entered the pass in multi-input mode. They were inserted only when the module key was empty — the root module, which in multi-input mode no file occupies. A service clashing with a model in its own file rejected when that file was the sole input, and was silently accepted when the same file sat in a directory.
• Go was scoped per module, but flattens every module into one package. Two input files each declaring a Page emitted type Page struct twice into that package, with no diagnostic. Confirmed with the Go type checker: Page redeclared in this block.
• Making Go's scope package-wide was not enough on its own. A collision is detected by identifier, and two models named Page in different modules produced the identical origin string type `Page` — which the namespace read as one declaration re-inserted rather than a clash. Origins now carry the module-qualified name, so the dedupe fires only for what is genuinely one declaration seen twice, and the diagnostic names both sides (a/page#Page and b/page#Page).
• A TypeScript service identifier was derived as a type name while the generator emits a lower-camel const. That produced a false rejection — chatService and ChatService are distinct identifiers and generate cleanly — and missed the clash TypeScript really has: a service whose lower-camel form lands on a model's <model>TransferTypeConverter. Widening service insertion while the derivation was wrong would have spread the false positive into every module, so it had to come along. Manifest-only; no emitted name changes.

931f5d2 — TypeScript and Python resolve run-wide too

The same cross-module defect as Go, by a different route: both emit a root barrel that lifts every module's top-level names into one namespace — index.ts re-exporting each module with export *, __init__.py re-exporting them by name. Two input files each declaring a Page collide there.

Left to the target, TypeScript emits a barrel its own compiler rejects (TS2308, and the model's pageTransferTypeConverter collides alongside the interface). Python is worse: from .a import Page followed by from .b import Page raises nothing, binds the second, and lists the name once in __all__ — so from pkg import Page quietly resolves to the wrong model, the silent incorrectness P7 exists to prevent.

Java and .NET are genuinely unaffected, and this was checked against both generators rather than inferred from the directory layout: each module lands in its own sub-package/namespace (com.example.api.a.page, Nexgen.Generated.A.Page) and neither emits an aggregating barrel, so two Page types stay distinct.

The scope is now chosen by a documented predicate over the emitted layout instead of a Go special case, since the reason differs per target. PRINCIPLES.md §15, generated-file-layout.md, and ref.md all asserted the superseded rule and are corrected — ref.md had claimed one package-wide namespace for every target.

3a3575a — a $ref'd type is emitted only by its declaring module

A module re-emitted the types it only $refd from another input file whenever that module declared no types of its own — a service file whose every operation type is a $ref elsewhere. Every target emitted a second copy:

	symptom
Go	Page redeclared in this block (go build)
Java	duplicate Page.java, build fails with a generated-file conflict
TypeScript	module both imports and redeclares the name (TS2440), barrel re-exports it twice (TS2308)
Python	two classes; barrel imports both and silently binds one (P7)
.NET	duplicate class

The cause was in reachability pruning, which decides whether to drop declarations another module owns. It inferred "this front end does not scope declarations by module" from the module owning nothing — a state indistinguishable from "this module declares nothing" while the flag is a bool, so a service-only JSON module looked like a WIT spec and kept everything it could reach. A declaration now records Foreign distinctly from Unscoped, which is the distinction the prune was actually reaching for.

Dropping the re-emitted copies leaves such a module with an empty models.ts, and a barrel re-exporting a file with no exports is itself an error (TS2306), so TypeScript now emits neither the file nor the ./models re-export.

Why no sample churn. Every checked-in sample service module happens to declare at least one inline operation type, which suppresses the bug entirely — adding one unrelated inline type to a broken module makes it vanish. That is why this went unnoticed, and it was pinned down by bisecting from the working kb sample down to the trigger. Each of the four new regression tests was confirmed to fail without the fix, and the repaired output was checked with the Go compiler, javac, tsc, and a Python import rather than by inspection.

Also

unique_temp_dir in the test suite derived its path from the wall clock alone, while six tests pass write_oneof_descriptor one fixed name — two threads reading the same timestamp shared a directory and fs::write the same api.bin concurrently, so a third could read it truncated mid-write. The clock's granularity, not the test, decided whether the run was green. A process-wide counter now joins the path.

[bergundy]

./scripts/validate.sh passes at 35ca5c6 (all Rust tests plus the Go/TypeScript/Python/Java sample suites; regeneration leaves the tree clean).