ts-procedures 10.2.2 → 10.3.0

package/build/server/scope-name-collision.d.ts

@@ -0,0 +1,17 @@
+import type { AnyProcedureRegistration } from '../core/types.js';
+/**
+ * The identifier a procedure generates in the client. Built from the same
+ * shared naming primitives the codegen emitters use, so the two cannot disagree:
+ * - `rpc` / `rpc-stream` → `versionedPascal(name, version)` (V{n} when version > 1)
+ * - `http` / `http-stream` → `toPascalCase(name)` (no version suffix)
+ */
+export declare function generatedRouteName(procedure: AnyProcedureRegistration<any, any>): string;
+/**
+ * Throws a {@link ProcedureRegistrationError} if any two procedures collapse to
+ * the same `(scope, generatedName)`. No-op when every procedure is distinct.
+ *
+ * Call this once with every procedure that will be served on a single app —
+ * including procedures contributed by separate factories — since cross-factory
+ * collisions are the case the per-factory registry can't see.
+ */
+export declare function assertNoScopeNameCollisions(procedures: Iterable<AnyProcedureRegistration<any, any>>): void;

package/build/server/scope-name-collision.js

@@ -0,0 +1,99 @@
+/**
+ * Server-start guard that mirrors the codegen TS emitter's per-scope name
+ * collision check (`src/codegen/emit/scope-file.ts`).
+ *
+ * The core registry only enforces that raw procedure NAMES are unique within a
+ * single factory. That misses two cases the client codegen rejects — and which
+ * therefore produce a server that boots happily but can never have a working
+ * generated client:
+ *
+ *   1. Two names in the same scope that PascalCase to the same identifier
+ *      (e.g. `get-task` and `getTask` → `GetTask`), and
+ *   2. The same `(scope, name)` registered across two different factories that
+ *      are mounted on one app (each factory has its own registry, so neither
+ *      duplicate check fires).
+ *
+ * Both collapse to a single generated type + callable key in the emitted client
+ * (duplicate identifier / duplicate object key), which is exactly what
+ * `emitScopeFile` throws on. We surface the same failure at server start, with a
+ * trace pointing at every colliding definition site, so it's caught in the
+ * server developer's own codebase instead of downstream at codegen time.
+ */
+import { ProcedureRegistrationError } from '../core/errors.js';
+import { normalizeScope, toPascalCase, versionedPascal } from '../naming.js';
+/**
+ * The identifier a procedure generates in the client. Built from the same
+ * shared naming primitives the codegen emitters use, so the two cannot disagree:
+ * - `rpc` / `rpc-stream` → `versionedPascal(name, version)` (V{n} when version > 1)
+ * - `http` / `http-stream` → `toPascalCase(name)` (no version suffix)
+ */
+export function generatedRouteName(procedure) {
+    if (procedure.kind === 'rpc' || procedure.kind === 'rpc-stream') {
+        return versionedPascal(procedure.name, procedure.config.version);
+    }
+    return toPascalCase(procedure.name);
+}
+/** The scope grouping key codegen would file this procedure under. */
+function scopeKeyOf(procedure) {
+    return normalizeScope(procedure.config.scope);
+}
+function definedAtString(info) {
+    const at = info?.definedAt;
+    return at ? ` (defined at ${at.file}:${at.line}:${at.column})` : '';
+}
+/**
+ * Throws a {@link ProcedureRegistrationError} if any two procedures collapse to
+ * the same `(scope, generatedName)`. No-op when every procedure is distinct.
+ *
+ * Call this once with every procedure that will be served on a single app —
+ * including procedures contributed by separate factories — since cross-factory
+ * collisions are the case the per-factory registry can't see.
+ */
+export function assertNoScopeNameCollisions(procedures) {
+    // scopeKey → generatedName → procedures that produced it
+    const byScope = new Map();
+    for (const procedure of procedures) {
+        const scopeKey = scopeKeyOf(procedure);
+        const generated = generatedRouteName(procedure);
+        let byName = byScope.get(scopeKey);
+        if (byName === undefined) {
+            byName = new Map();
+            byScope.set(scopeKey, byName);
+        }
+        const existing = byName.get(generated);
+        if (existing === undefined)
+            byName.set(generated, [procedure]);
+        else
+            existing.push(procedure);
+    }
+    const collisions = [];
+    for (const [scopeKey, byName] of byScope) {
+        for (const [generated, procs] of byName) {
+            if (procs.length > 1)
+                collisions.push({ scopeKey, generated, procs });
+        }
+    }
+    if (collisions.length === 0)
+        return;
+    const details = collisions
+        .map(({ scopeKey, generated, procs }) => {
+        const lines = procs
+            .map((p) => `      - "${p.name}" (${p.kind})${definedAtString(p.definitionInfo)}`)
+            .join('\n');
+        return `  Scope "${scopeKey}" → generated name "${generated}":\n${lines}`;
+    })
+        .join('\n');
+    // Anchor the error (and its appended definition-site frame) on the first
+    // colliding procedure; the message enumerates every collision.
+    const first = collisions[0].procs[0];
+    throw new ProcedureRegistrationError(first.name, `Procedure name collision — the server cannot start.\n\n` +
+        `These procedures collapse to the same generated client identifier within the same scope. ` +
+        `The generated client would emit duplicate types and a duplicate callable key for each pair ` +
+        `(this is the same failure the codegen rejects), so the server refuses to start rather than ` +
+        `boot a config no client can be generated for:\n\n` +
+        `${details}\n\n` +
+        `Names are PascalCased per scope, so different raw names can still collide ` +
+        `(e.g. "get-task" and "getTask" both become "GetTask"). Rename one procedure in each pair, ` +
+        `or move it to a different scope, so every procedure in a scope generates a distinct name.`, first.definitionInfo);
+}
+//# sourceMappingURL=scope-name-collision.js.map

package/build/server/scope-name-collision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-name-collision.js","sourceRoot":"","sources":["../../src/server/scope-name-collision.ts"],"names":[],"mappings":"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"}

package/build/server/scope-name-collision.test.d.ts

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

package/build/server/scope-name-collision.test.js

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'vitest';
+import { Procedures } from '../core/procedures.js';
+import { ProcedureRegistrationError } from '../core/errors.js';
+import { toPascalCase, versionedPascal } from '../naming.js';
+import { assertNoScopeNameCollisions, generatedRouteName } from './scope-name-collision.js';
+describe('generatedRouteName — per-kind dispatch', () => {
+    // generatedRouteName routes each kind to the right shared naming primitive
+    // (versionedPascal for rpc/rpc-stream, toPascalCase for http kinds) — the same
+    // primitives the codegen emitters use, so the guard and codegen can't disagree.
+    test('rpc / rpc-stream match versionedPascal(name, version)', () => {
+        const cases = [
+            { name: 'get-task', version: 1 },
+            { name: 'getTask', version: 2 },
+            { name: 'log_out', version: 3 },
+            { name: 'Foo', version: 1 },
+        ];
+        for (const { name, version } of cases) {
+            const rpc = { name, kind: 'rpc', config: { version } };
+            const stream = { name, kind: 'rpc-stream', config: { version } };
+            expect(generatedRouteName(rpc)).toBe(versionedPascal(name, version));
+            expect(generatedRouteName(stream)).toBe(versionedPascal(name, version));
+        }
+    });
+    test('http / http-stream match toPascalCase(name), ignoring any version', () => {
+        for (const name of ['get-user', 'getUser', 'log out', 'list_items']) {
+            const http = { name, kind: 'http', config: { method: 'get', path: '/x', version: 9 } };
+            const httpStream = { name, kind: 'http-stream', config: { method: 'get', path: '/x' } };
+            expect(generatedRouteName(http)).toBe(toPascalCase(name));
+            expect(generatedRouteName(httpStream)).toBe(toPascalCase(name));
+        }
+    });
+    test('version 1 produces no V suffix; version > 1 does', () => {
+        const v1 = { name: 'Thing', kind: 'rpc', config: { version: 1 } };
+        const v2 = { name: 'Thing', kind: 'rpc', config: { version: 2 } };
+        expect(generatedRouteName(v1)).toBe('Thing');
+        expect(generatedRouteName(v2)).toBe('ThingV2');
+    });
+});
+describe('assertNoScopeNameCollisions', () => {
+    test('no-op when every procedure generates a distinct scoped name', () => {
+        const P = Procedures();
+        P.Create('GetTask', { scope: 'tasks', version: 1 }, async () => ({}));
+        P.Create('ListTasks', { scope: 'tasks', version: 1 }, async () => ({}));
+        expect(() => assertNoScopeNameCollisions(P.getProcedures())).not.toThrow();
+    });
+    test('same name in DIFFERENT scopes is allowed (separate scope files)', () => {
+        const A = Procedures();
+        A.Create('Get', { scope: 'users', version: 1 }, async () => ({}));
+        const B = Procedures();
+        B.Create('Get', { scope: 'orders', version: 1 }, async () => ({}));
+        expect(() => assertNoScopeNameCollisions([...A.getProcedures(), ...B.getProcedures()])).not.toThrow();
+    });
+    test('detects names that pascalize to the same identifier in one scope', () => {
+        const P = Procedures();
+        // distinct raw names → both register on the core registry...
+        P.Create('get-task', { scope: 'tasks', version: 1 }, async () => ({}));
+        P.Create('getTask', { scope: 'tasks', version: 1 }, async () => ({}));
+        // ...but both pascalize to "GetTask".
+        expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(ProcedureRegistrationError);
+        expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(/GetTask/);
+    });
+    test('detects the same (scope, name) contributed by two separate factories', () => {
+        const A = Procedures();
+        A.Create('LogOut', { scope: 'auth', version: 1 }, async () => ({}));
+        const B = Procedures();
+        B.Create('LogOut', { scope: 'auth', version: 1 }, async () => ({}));
+        const all = [...A.getProcedures(), ...B.getProcedures()];
+        expect(() => assertNoScopeNameCollisions(all)).toThrow(/Scope "auth".*LogOut/s);
+    });
+    test('version disambiguates: Foo@v1 and Foo@v2 (across factories) do not collide', () => {
+        // Same raw name can't register twice in one factory, but two factories can
+        // each contribute a "Foo" — distinct versions keep their generated names apart.
+        const A = Procedures();
+        A.Create('Foo', { scope: 's', version: 1 }, async () => ({}));
+        const B = Procedures();
+        B.Create('Foo', { scope: 's', version: 2 }, async () => ({}));
+        expect(() => assertNoScopeNameCollisions([...A.getProcedures(), ...B.getProcedures()])).not.toThrow();
+    });
+    test('version collision: Foo@v2 and FooV2@v1 both generate "FooV2"', () => {
+        const P = Procedures();
+        P.Create('Foo', { scope: 's', version: 2 }, async () => ({}));
+        P.Create('FooV2', { scope: 's', version: 1 }, async () => ({}));
+        expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(/FooV2/);
+    });
+    test('rpc and http procedures collide when they share scope + generated name', () => {
+        const A = Procedures();
+        A.Create('Thing', { scope: 'mix', version: 1 }, async () => ({}));
+        const B = Procedures();
+        B.CreateHttp('Thing', { scope: 'mix', path: '/thing', method: 'get' }, async () => undefined);
+        expect(() => assertNoScopeNameCollisions([...A.getProcedures(), ...B.getProcedures()])).toThrow(/Thing/);
+    });
+    test('procedures with no scope are grouped under "default" and can collide', () => {
+        const P = Procedures();
+        P.CreateHttp('do-thing', { path: '/a', method: 'get' }, async () => undefined);
+        P.CreateHttp('doThing', { path: '/b', method: 'get' }, async () => undefined);
+        expect(() => assertNoScopeNameCollisions(P.getProcedures())).toThrow(/Scope "default".*DoThing/s);
+    });
+    test('error message names both procedures and includes their definition sites', () => {
+        const P = Procedures();
+        P.Create('get-task', { scope: 'tasks', version: 1 }, async () => ({}));
+        P.Create('getTask', { scope: 'tasks', version: 1 }, async () => ({}));
+        let caught;
+        try {
+            assertNoScopeNameCollisions(P.getProcedures());
+        }
+        catch (err) {
+            caught = err;
+        }
+        expect(caught).toBeInstanceOf(ProcedureRegistrationError);
+        expect(caught.message).toContain('"get-task"');
+        expect(caught.message).toContain('"getTask"');
+        expect(caught.message).toContain('GetTask');
+        // definition site captured at registration flows into the trace
+        expect(caught.message).toContain('scope-name-collision.test.ts');
+        expect(caught.getDefinitionLocation()).toContain('scope-name-collision.test.ts');
+    });
+    test('reports every colliding group in one error', () => {
+        const P = Procedures();
+        P.Create('a-one', { scope: 's', version: 1 }, async () => ({}));
+        P.Create('aOne', { scope: 's', version: 1 }, async () => ({}));
+        P.Create('b-two', { scope: 's', version: 1 }, async () => ({}));
+        P.Create('bTwo', { scope: 's', version: 1 }, async () => ({}));
+        let message = '';
+        try {
+            assertNoScopeNameCollisions(P.getProcedures());
+        }
+        catch (err) {
+            message = err.message;
+        }
+        expect(message).toContain('AOne');
+        expect(message).toContain('BTwo');
+    });
+});
+//# sourceMappingURL=scope-name-collision.test.js.map

package/build/server/scope-name-collision.test.js.map

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

package/docs/client-and-codegen.md

@@ -152,7 +152,7 @@ generated/
 
 Codegen fails fast (non-zero exit) rather than emitting a client that won't compile:
 
-- **Route-name collisions.** Two routes in the same scope whose names PascalCase to the same identifier (e.g. `get-task` and `getTask`, or `Foo` at version 2 and a literal `FooV2`) would emit a merged namespace with duplicate types and a duplicated callable key. Codegen throws naming both routes — rename one.
+- **Route-name collisions.** Two routes in the same scope whose names PascalCase to the same identifier (e.g. `get-task` and `getTask`, or `Foo` at version 2 and a literal `FooV2`) would emit a merged namespace with duplicate types and a duplicated callable key. Codegen throws naming both routes — rename one. The same collision is now also rejected at **server start** (`HonoAppBuilder.build()` throws a `ProcedureRegistrationError` pointing at every colliding definition), so it surfaces in your server before it ever reaches codegen — including the cross-factory case where two factories each contribute the same `(scope, name)` and neither factory's registry can see the other.
 - **`--service-name` vs scope collisions.** A scope whose PascalCase name equals `--service-name` (e.g. scope `godmode` with `--service-name Godmode`) would emit two `GodmodeClient` declarations. Codegen throws — rename the scope or change `--service-name`.
 - **`--check` self-validation.** Opt in to validate the *whole* emitted output before trusting it (see the flag table above). Use it in CI so a generator regression can never silently overwrite a working client with a broken one.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "10.2.2",
+  "version": "10.3.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",

package/src/adapters/hono/index.test.ts

@@ -395,3 +395,39 @@ describe('HonoAppBuilder — middleware (new)', () => {
     expect(calls).toContain('used')
   })
 })
+
+describe('HonoAppBuilder — scope/name collision guard', () => {
+  test('build() crashes when two routes pascalize to the same name in a scope', () => {
+    const P = Procedures<object, RPCConfig>()
+    // distinct raw names register fine on the core registry...
+    P.Create('get-task', { scope: 'tasks', version: 1 }, async () => ({}))
+    P.Create('getTask', { scope: 'tasks', version: 1 }, async () => ({}))
+
+    const b = new HonoAppBuilder()
+    b.register(P, () => ({}))
+    // ...but both generate "GetTask", which the client codegen rejects.
+    expect(() => b.build()).toThrow(/Scope "tasks".*GetTask/s)
+  })
+
+  test('build() crashes on the same (scope, name) contributed by two factories', () => {
+    const A = Procedures<object, RPCConfig>()
+    A.Create('LogOut', { scope: 'auth', version: 1 }, async () => ({}))
+    const B = Procedures<object, RPCConfig>()
+    B.Create('LogOut', { scope: 'auth', version: 1 }, async () => ({}))
+
+    const b = new HonoAppBuilder()
+    b.register(A, () => ({}))
+    b.register(B, () => ({}))
+    expect(() => b.build()).toThrow(/LogOut/)
+  })
+
+  test('build() succeeds when scoped names are all distinct', () => {
+    const P = Procedures<object, RPCConfig>()
+    P.Create('GetTask', { scope: 'tasks', version: 1 }, async () => ({}))
+    P.Create('ListTasks', { scope: 'tasks', version: 1 }, async () => ({}))
+
+    const b = new HonoAppBuilder()
+    b.register(P, () => ({}))
+    expect(() => b.build()).not.toThrow()
+  })
+})

package/src/adapters/hono/index.ts

@@ -10,6 +10,7 @@ import type {
 } from '../../server/types.js'
 import type { AnyProcedureRegistration } from '../../core/types.js'
 import { DocRegistry } from '../../server/doc-registry.js'
+import { assertNoScopeNameCollisions } from '../../server/scope-name-collision.js'
 import type { ErrorTaxonomy } from '../../server/errors/taxonomy.js'
 import type { FactoryContextInit } from '../../server/context.js'
 import { buildRpcRouteDoc } from '../../server/docs/rpc-doc.js'
@@ -145,6 +146,13 @@ export class HonoAppBuilder<TStreamErrorData = unknown> {
     return this
   }
 
+  /** Every procedure across every registered factory, in registration order. */
+  private *allProcedures(): Iterable<AnyProcedureRegistration<any, any>> {
+    for (const item of this.factories) {
+      yield* item.factory.getProcedures().values() as Iterable<AnyProcedureRegistration<any, any>>
+    }
+  }
+
   private computeDocs(): void {
     const docs: AnyHttpRouteDoc[] = []
     const skipped: { name: string; reason: string }[] = []
@@ -190,6 +198,14 @@ export class HonoAppBuilder<TStreamErrorData = unknown> {
     if (this._built) return this._app
     this._built = true
 
+    // Fail fast on procedures that would collapse to the same generated client
+    // identifier within a scope (e.g. `get-task`/`getTask`, or the same
+    // `(scope, name)` contributed by two factories). The per-factory registry
+    // can't catch these — but the client codegen rejects them — so crash here
+    // with a trace to every colliding definition instead of booting a server no
+    // client can be generated for.
+    assertNoScopeNameCollisions(this.allProcedures())
+
     const docs: AnyHttpRouteDoc[] = []
     const skipped: { name: string; reason: string }[] = []
     const cfg = this.config ?? {}

package/src/codegen/emit/route-shared.ts

@@ -6,15 +6,9 @@
 import { toPascalCase } from '../naming.js'
 import type { EmitRouteContext } from './context.js'
 
-/**
- * Returns the PascalCase display name for a route, appending `V{version}`
- * when version > 1. Version 1 produces no suffix for backward compatibility.
- */
-export function versionedPascal(name: string, version: number | undefined): string {
-  const pascal = toPascalCase(name)
-  if (version != null && version > 1) return `${pascal}V${version}`
-  return pascal
-}
+// `versionedPascal` now lives in the neutral naming module (shared with the
+// server-start collision guard); re-exported here to keep its import path stable.
+export { versionedPascal } from '../../naming.js'
 
 // ---------------------------------------------------------------------------
 // Route-level Errors union injection

package/src/codegen/group-routes.ts

@@ -1,4 +1,9 @@
 import type { AnyHttpRouteDoc } from '../server/types.js'
+import { normalizeScope } from '../naming.js'
+
+// Re-exported so existing `./group-routes.js` importers keep working; the
+// definition is shared with the server-start collision guard (see src/naming.ts).
+export { normalizeScope }
 
 export interface ScopeGroup {
   scopeKey: string
@@ -6,18 +11,6 @@ export interface ScopeGroup {
   routes: AnyHttpRouteDoc[]
 }
 
-/**
- * Normalizes a scope value to a string key:
- * - string   → returned as-is
- * - string[] → joined with '-'
- * - undefined → 'default'
- */
-export function normalizeScope(scope: string | string[] | undefined): string {
-  if (scope === undefined) return 'default'
-  if (Array.isArray(scope)) return scope.join('-')
-  return scope
-}
-
 /**
  * Converts a hyphenated scope key to camelCase.
  * e.g. 'admin-users' → 'adminUsers', 'users' → 'users'

package/src/codegen/naming.ts

@@ -1,10 +1,7 @@
-/** Converts a string to PascalCase (splits on whitespace, hyphens, underscores). */
-export function toPascalCase(str: string): string {
-  return str
-    .split(/[\s\-_]+/)
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join('')
-}
+// Re-exported from the neutral naming module so codegen and the server-start
+// collision guard share one definition (see src/naming.ts).
+import { toPascalCase } from '../naming.js'
+export { toPascalCase }
 
 /**
  * Validates that a serviceName option is usable as a TypeScript identifier fragment.

package/src/core/create-http-stream.ts

@@ -176,6 +176,7 @@ export function makeCreateHttpStream<TContext>(runtime: FactoryRuntime<TContext,
     const registeredProcedure: THttpStreamProcedureRegistration<TContext> = {
       name,
       kind: 'http-stream',
+      definitionInfo,
       config: {
         path,
         method: config.method,

package/src/core/create-http.ts

@@ -91,6 +91,7 @@ export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>)
     const registeredProcedure: THttpProcedureRegistration<TContext> = {
       name,
       kind: 'http',
+      definitionInfo,
       config: {
         path,
         method: config.method,

package/src/core/create-stream.ts

@@ -63,6 +63,7 @@ export function makeCreateStream<TContext, TExtendedConfig>(runtime: FactoryRunt
     const registeredProcedure: TStreamProcedureRegistration<TContext, TExtendedConfig> = {
       name,
       kind: 'rpc-stream',
+      definitionInfo,
       config: {
         ...config,
         description: config.description,

package/src/core/create.ts

@@ -58,6 +58,7 @@ export function makeCreate<TContext, TExtendedConfig>(runtime: FactoryRuntime<TC
     const registeredProcedure: TProcedureRegistration<TContext, TExtendedConfig> = {
       name,
       kind: 'rpc',
+      definitionInfo,
       config: {
         ...config,
         description: config.description,

package/src/core/types.ts

@@ -1,4 +1,5 @@
 import type * as AJV from 'ajv'
+import type { DefinitionInfo } from './definition-site.js'
 import type { ProcedureError } from './errors.js'
 import type { SchemaAdapter } from '../schema/adapter.js'
 import type { Infer, Prettify, TJSONSchema } from '../schema/json-schema.js'
@@ -35,6 +36,8 @@ export type ProcedureKind = 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
 export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
   name: string
   kind: 'rpc'
+  /** Source location where the procedure was defined; powers actionable error traces. */
+  definitionInfo?: DefinitionInfo
   config: {
     description?: string
     schema?: {
@@ -51,6 +54,8 @@ export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown
 export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
   name: string
   kind: 'rpc-stream'
+  /** Source location where the procedure was defined; powers actionable error traces. */
+  definitionInfo?: DefinitionInfo
   config: {
     description?: string
     schema?: {
@@ -145,6 +150,8 @@ export type TCreateHttpConfig<
 export type THttpProcedureRegistration<TContext = unknown> = {
   name: string
   kind: 'http'
+  /** Source location where the procedure was defined; powers actionable error traces. */
+  definitionInfo?: DefinitionInfo
   config: {
     path: string
     method: HttpMethod
@@ -166,6 +173,8 @@ export type THttpProcedureRegistration<TContext = unknown> = {
 export type THttpStreamProcedureRegistration<TContext = unknown> = {
   name: string
   kind: 'http-stream'
+  /** Source location where the procedure was defined; powers actionable error traces. */
+  definitionInfo?: DefinitionInfo
   config: {
     path: string
     method: HttpMethod

package/src/naming.ts

@@ -0,0 +1,38 @@
+/**
+ * Identifier-naming primitives shared by the codegen emitters and the
+ * server-start collision guard. These MUST agree byte-for-byte across both —
+ * the server refuses to start a config the codegen would reject, and that only
+ * holds if both compute generated names the same way. Keeping them in one
+ * neutral module (imported by `src/codegen/*` and `src/server/*` alike) makes
+ * that a structural guarantee instead of a parity test.
+ */
+
+/** Converts a string to PascalCase (splits on whitespace, hyphens, underscores). */
+export function toPascalCase(str: string): string {
+  return str
+    .split(/[\s\-_]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('')
+}
+
+/**
+ * Returns the PascalCase display name for a route, appending `V{version}`
+ * when version > 1. Version 1 produces no suffix for backward compatibility.
+ */
+export function versionedPascal(name: string, version: number | undefined): string {
+  const pascal = toPascalCase(name)
+  if (version != null && version > 1) return `${pascal}V${version}`
+  return pascal
+}
+
+/**
+ * Normalizes a scope value to a string grouping key:
+ * - string   → returned as-is
+ * - string[] → joined with '-'
+ * - undefined → 'default'
+ */
+export function normalizeScope(scope: string | string[] | undefined): string {
+  if (scope === undefined) return 'default'
+  if (Array.isArray(scope)) return scope.join('-')
+  return scope
+}

package/src/server/index.ts

@@ -27,3 +27,4 @@ export { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
 export { DocRegistry } from './doc-registry.js'
 export { writeDocEnvelope } from './doc-envelope.js'
 export type { DocEnvelopeSource } from './doc-envelope.js'
+export { assertNoScopeNameCollisions, generatedRouteName } from './scope-name-collision.js'