@spfn/core 0.3.0-beta.10 → 0.3.0-beta.12

package/dist/{types-9oszaJqp.d.ts → types-yv6z_mK7.d.ts}

@@ -62,13 +62,112 @@ type InferRouteInput<TRoute> = TRoute extends RouteDef<infer TInput, any, any> ?
  * ```
  */
 type InferRouteOutput<TRoute> = TRoute extends RouteDef<any, any, infer TResponse> ? TResponse : never;
+/**
+ * True only for `any`.
+ *
+ * `any` satisfies both branches of a conditional type, so a router whose routes are
+ * unresolved (`Router<any>`) would otherwise flatten into "every name exists" and
+ * accept a misspelled route name. A route record that is not known contributes no
+ * names instead.
+ */
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+/**
+ * True when `T` is a union of two or more members.
+ */
+type IsUnion<T, TCopy = T> = T extends unknown ? ([TCopy] extends [T] ? false : true) : false;
+/**
+ * One leaf of a router tree: the name a route is registered under, its definition, and
+ * the path it was reached by.
+ *
+ * A route is identified by its own key whatever depth it sits at — `registerRoutes`
+ * mounts a nested route under that key, and the contract collector reports a collision
+ * on it. Nesting groups the source; it does not qualify the name. The trail is carried
+ * so that one name reached through two branches stays two leaves.
+ */
+interface RouteLeaf<TName extends PropertyKey, TDef, TTrail extends PropertyKey[]> {
+    name: TName;
+    def: TDef;
+    trail: TTrail;
+}
+/** Decrements the nesting budget; `PrevDepth[0]` is `never`, which ends the walk. */
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/**
+ * How many levels of nesting are followed.
+ *
+ * A budget rather than open recursion: a router type that refers to itself would
+ * otherwise never terminate, and TypeScript would report an instantiation-depth error
+ * in whichever component happened to read a route type. A route below the budget is not
+ * visible to these types; ten levels is far past any hand-written tree.
+ */
+type MaxNesting = 10;
+/**
+ * Collect every route in a route record as a leaf, descending into nested routers
+ * exactly as `registerRoutes` does.
+ */
+type RouteLeaves<TRoutes, TTrail extends PropertyKey[] = [], TDepth extends number = MaxNesting> = [
+    TDepth
+] extends [never] ? never : IsAny<TRoutes> extends true ? never : {
+    [K in keyof TRoutes]-?: RouteLeafOf<K, Exclude<TRoutes[K], undefined>, [...TTrail, K], TDepth>;
+}[keyof TRoutes];
+/**
+ * A nested router contributes its own leaves; anything else is a leaf.
+ *
+ * `{ _routes: ... }` is the runtime's own test for a router (`isRouter`), and a
+ * `RouteDef` carries `handler`, `_input` and `_response` but never `_routes`, so a
+ * route cannot be mistaken for a router.
+ */
+type RouteLeafOf<TName extends PropertyKey, TValue, TTrail extends PropertyKey[], TDepth extends number> = TValue extends {
+    _routes: infer TNested;
+} ? RouteLeaves<TNested, TTrail, PrevDepth[TDepth]> : RouteLeaf<TName, TValue, TTrail>;
+/** Every name the tree declares. */
+type LeafNames<TLeaves> = Extract<TLeaves extends RouteLeaf<infer TName, any, any> ? TName : never, PropertyKey>;
+/**
+ * The leaves declaring exactly this name.
+ *
+ * Exactly, not assignably: a record typed `Record<string, RouteDef>` contributes the
+ * name `string`, which every literal name is assignable to, and a loose sibling must
+ * not make each of its siblings look doubly declared.
+ */
+type LeavesNamed<TLeaves, TName extends PropertyKey> = TLeaves extends RouteLeaf<infer TLeafName, any, any> ? [TLeafName] extends [TName] ? [TName] extends [TLeafName] ? TLeaves : never : never : never;
+/** The definition a leaf carries. */
+type LeafDef<TLeaves> = TLeaves extends RouteLeaf<any, infer TDef, any> ? TDef : never;
+/** Where a leaf was found — one distinct trail per place the name is declared. */
+type LeafTrail<TLeaves> = TLeaves extends RouteLeaf<any, any, infer TTrail> ? TTrail : never;
+/**
+ * Flatten the leaves into one namespace of name → definition.
+ *
+ * A name that two branches both declare is left out rather than resolved to one of
+ * them: the tree gives it no single meaning, and picking a winner silently would hand
+ * a component another route's types. Naming it then fails the `K` constraint on
+ * `RouterOutput`/`RouterInput`, on the line that named it. Two places is counted by
+ * trail, so one slot holding a union of route definitions stays one route and still
+ * infers the union.
+ *
+ * The result is a fresh mapped type, so no key carries an optional or readonly modifier
+ * out of the source record — a route key that turned optional would change what
+ * `InferRouteInput` returns for it.
+ */
+type FlattenLeaves<TLeaves> = {
+    [TName in LeafNames<TLeaves> as UnambiguousName<TLeaves, TName>]: LeafDef<LeavesNamed<TLeaves, TName>>;
+};
+/** The name itself when one place declares it, and nothing when two do. */
+type UnambiguousName<TLeaves, TName extends PropertyKey> = IsUnion<LeafTrail<LeavesNamed<TLeaves, TName>>> extends true ? never : TName;
 /**
  * Extract routes from Router type
- * Router<TRoutes> has routes in `_routes` property
+ *
+ * `Router<TRoutes>` holds its routes in `_routes`, and a value in that record is either
+ * a route or another router. Nested routers are flattened away, so every route appears
+ * here under its own name at one level — the same set of names the server registers.
+ *
+ * Exported so that the typed client (`Client`, in `./builder`) names a route the same
+ * way `RouterOutput` and `RouterInput` do; the two must not diverge, or a route would
+ * type in one place and not the other. It stays internal to the package: the
+ * `@spfn/core/nextjs` entry point exports a fixed list of type names, and this is not
+ * one of them.
  */
 type ExtractRoutes<TRouter> = TRouter extends {
     _routes: infer TRoutes;
-} ? TRoutes : TRouter;
+} ? FlattenLeaves<RouteLeaves<TRoutes>> : FlattenLeaves<RouteLeaves<TRouter>>;
 /**
  * Extract output type for a specific route from router
  *
@@ -88,6 +187,23 @@ type ExtractRoutes<TRouter> = TRouter extends {
  * // Extract item type from paginated response
  * type Example = RouterOutput<AppRouter, 'listExamples'>['items'][number];
  * ```
+ *
+ * A route declared inside a nested router is named the same way. The server registers
+ * a nested route under its own key, so `K` is the flat set of route names in the tree
+ * and the depth the route was declared at never appears here:
+ *
+ * ```typescript
+ * const appRouter = defineRouter({
+ *     getRoot,
+ *     examples: defineRouter({ listExamples, createExample }),
+ * });
+ *
+ * type ListData = RouterOutput<typeof appRouter, 'listExamples'>;
+ * ```
+ *
+ * Two branches declaring the same name make that name ambiguous, and it is left out of
+ * `K` rather than resolved to one of them — naming it is a compile error here instead
+ * of the wrong route's types reaching a component.
  */
 type RouterOutput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteOutput<ExtractRoutes<TRouter>[K]>;
 /**
@@ -106,6 +222,9 @@ type RouterOutput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteO
  *     // ...
  * }
  * ```
+ *
+ * `K` is the flat set of route names, so a route declared inside a nested router is
+ * named by its own key here too — see {@link RouterOutput}.
  */
 type RouterInput<TRouter, K extends keyof ExtractRoutes<TRouter>> = InferRouteInput<ExtractRoutes<TRouter>[K]>;
 /**
@@ -247,4 +366,4 @@ interface CallOptions {
     };
 }
 
-export type { ApiConfig as A, CallOptions as C, InferRouteInput as I, RequestInterceptor as R, SetCookie as S, ResponseInterceptor as a, InferRouteOutput as b, CookieOptions as c, RouterInput as d, RouterOutput as e, StructuredInput as f };
+export type { ApiConfig as A, CallOptions as C, ExtractRoutes as E, InferRouteInput as I, RequestInterceptor as R, SetCookie as S, ResponseInterceptor as a, InferRouteOutput as b, CookieOptions as c, RouterInput as d, RouterOutput as e, StructuredInput as f };

package/docs/file-upload.md

@@ -229,8 +229,8 @@ export const uploadImage = route.post('/images')
 
 ### `@spfn/storage` (recommended)
 
-SPFN ships provider-agnostic object storage — S3-compatible services (S3, R2, MinIO,
-Wasabi), Google Cloud Storage, and the local filesystem behind one interface. Prefer it
+SPFN ships provider-agnostic object storage — S3-compatible services (S3, R2, Wasabi,
+SeaweedFS), Google Cloud Storage, and the local filesystem behind one interface. Prefer it
 over calling a provider SDK directly: every object operation validates its key before it
 reaches the provider (rejecting `..` segments, leading `/`, backslashes, control
 characters and URLs), so a key built from user input cannot escape its prefix.
@@ -281,7 +281,7 @@ Three constraints decide whether this is safe:
 | Constraint | Behaviour |
 |---|---|
 | `contentLength` (exact size) | Signed on **both** S3-compatible and GCS. A mismatched size fails. |
-| `maxBytes` (upper bound) | Enforced on **GCS only**. A presigned PUT cannot sign a size range, so S3, R2, MinIO and Wasabi **ignore it silently**. |
+| `maxBytes` (upper bound) | Enforced on **GCS only**. A presigned PUT cannot sign a size range, so S3, R2 and Wasabi **ignore it silently**. |
 | Local filesystem provider | Presigned upload is **not supported** — `getUploadUrl()` throws. Use the direct `upload()` path in local dev. |
 
 A client can declare one size and send another, so a server-side check of a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spfn/core",
-    "version": "0.3.0-beta.10",
+    "version": "0.3.0-beta.12",
     "description": "Full-stack TypeScript backend for Next.js: file-based typed routes, Drizzle entities and repositories, PostgreSQL transactions and a generated end-to-end client, in one fixed vertical slice per feature",
     "type": "module",
     "exports": {

package/src/codegen/README.md

@@ -127,7 +127,7 @@ call `generators['route-map'](config)`.
 
 ## Built-in: `@spfn/core:route-map`
 
-Parses your router + route files and emits a `routeName → {method, path}` map. This map is
+Loads your router and emits a `routeName → {method, path}` map. This map is
 what the **RPC proxy** (`createRpcProxy` in `@spfn/core/nextjs/server`) uses to turn
 `api.getUser.call(...)` into an HTTP request — it needs `method` and `path` without
 importing server code into the client bundle.
@@ -139,18 +139,91 @@ importing server code into the client bundle.
 | `name` | `'@spfn/core:route-map'` | yes | — | Generator identifier (literal). |
 | `routerPath` | `string` | yes | — | Router file, relative to project root. Throws at construction if missing. |
 | `outputPath` | `string` | no | `'./src/generated/route-map.ts'` | Where the map is written (parent dirs auto-created). |
-| `additionalRouteDirs` | `string[]` | no | `[]` | Extra route dirs to watch (each becomes `${dir}/**/*.ts`). |
+| `additionalRouteDirs` | `string[]` | no | `[]` | **Deprecated and ignored** for collection; still added to `watchPatterns` as `${dir}/**/*.ts`. |
+
+### What it reads
+
+The router module is loaded with jiti (`appRouter` → `default` → `router`) and walked the
+way `registerRoutes` walks it. How the router is *written* does not matter: a one-line
+`defineRouter({ createUser })`, an aliased key `create: createUser`, and a second
+`defineRouter(` in the same file all produce the same map.
+
+- A **nested router** recurses to any depth and its routes land in the map **flat, under
+  their own keys** — the parent's key names the grouping, not the route, exactly as the
+  server registers them.
+- `method` and `path` come from the `RouteDef`, not from a pattern over the source. A
+  route not registered in the router is absent, because there is nothing registering it.
+- **`.packages()` routers are left out**, at every depth. A package publishes its own
+  route map and the app merges them (`{ ...routeMap, ...authRouteMap }`). Their *names*
+  are still read, because that merge is what a collision turns on — see below.
+- A name that is not a JS identifier (`'get-user'`) is emitted quoted, and `__proto__` is
+  emitted as a computed key, so the generated file parses and the map keeps every route as
+  an own property.
+- Imports are resolved by Node **and by the `compilerOptions.paths` of the nearest
+  `tsconfig.json` that declares them**, searched from the router file's own directory up to
+  the project root, `extends` chains included — so the `@/*` alias every spfn app has
+  resolves while the router loads, whether it lives in the root config (a Next.js app) or in
+  `src/server/tsconfig.json` (what `spfn init` scaffolds, and the config `spfn build`
+  compiles the server with). The search stops at the project root: a tsconfig above it
+  belongs to whatever contains the project. A config that declares no `paths` is passed over
+  rather than ending the search. `baseUrl` is honoured, so the scaffold's `"baseUrl": "../.."`
+  resolves against the project root as tsc resolves it. The failure names the specifier that
+  did not resolve.
+- `NODE_ENV` is pinned to `production` when the shell left it unset, so the same router
+  does not load two ways depending on how codegen was invoked. A value the shell *did* set
+  is left alone.
 
-### What it parses
+### When it refuses
 
-- **Router file** (`routerPath`): relative `import { ... } from './...'` statements, and the
-  route names listed inside the **first** `defineRouter({ ... })` call (top-level
-  identifiers, comments stripped).
-- **Route files**: only the exact pattern
-  `export const <name> = route.<get|post|put|patch|delete>('<path>')…` (single/double/back
-  quotes). The leading `route.<method>('<path>')` call is what's matched.
-- Only routes whose `name` also appears in `defineRouter({...})` end up in the output
-  (declared-but-unregistered routes are dropped).
+Unlike the old source parser, which dropped what it could not read, the generator throws
+— logged always, and fatal on the `build` trigger and on `spfn codegen run`:
+
+- The module will not load. An import that did not resolve names the specifier; anything
+  else names the cause and says a route module must be importable without side effects. It
+  never falls back to parsing.
+- No router is found under `appRouter`, `default` or `router` (the message lists all three).
+- The router file registers a route **conditionally** (`...(flag ? { admin } : {})`), which
+  would put the flag's value into the map and leave `api.admin.call()` 404ing wherever the
+  flag differs. This is the same guard `@spfn/core:contract` uses, and it reads **the router
+  the generator was pointed at** — the export the loader found it under, plus the routers
+  that export mounts by name from the same file, since a nested router's routes land in the
+  same flat map. A second `defineRouter(` the app router never reaches is not scanned: it
+  registers nothing in production. The source is read with TypeScript's parser, so a JSDoc
+  spelling `defineRouter({ ... })` in prose, a comment holding an old router and a brace
+  inside a string are not router source. Only a spread whose expression **reads a
+  condition** is refused — a ternary, `&&`, `||`, `??`. A call is allowed
+  (`...metadataRoutes(config, resource)`): loading yields exactly the routes it returns.
+  Past the guard, by construction: a conditional spread inside an imported module, a router
+  built by a factory, a condition hoisted to a variable before the spread, and a
+  `.packages()` list assembled conditionally. `NODE_ENV` pinning stands in for the guard on
+  those, but only when the shell left it unset: `spfn build` pins `production`, so what ships
+  is right, while `spfn dev` sets `development` and the watcher regenerates under it. The
+  generated header names the `NODE_ENV` the map was written under, so that difference is a
+  line in the diff rather than a route that vanishes at build.
+- Two routes reach the same name (the message names both places).
+- An **app route and a package route** reach the same name, where that package publishes a
+  route map. Both register at runtime, and the app's proxy merges
+  `{ ...routeMap, ...authRouteMap }` — so the package's route wins the name while the
+  generated types still describe the app's. Two *package* routers sharing a name is not
+  refused: which one wins is the app's merge order, which this generator neither sees nor
+  writes. Nor is a collision with a router that publishes **no** map — one declared with
+  `defineUnmappedRouter`, whose routes are reached by the URL something was handed rather
+  than by name: the ops surface (`createOpsRouter`), `@spfn/monitor`, `@spfn/cms` and the
+  tracking routes of `@spfn/notification`. Nothing of theirs merges over the app's map, so
+  an app route named after one of their routes overwrites nothing and must not fail the
+  build.
+- A route's `method` is not an `HttpMethod`. `registerRoutes` lowercases the method before
+  registering, so `method: 'get'` serves fine and would emit a map that fails `tsc`.
+
+A **missing router file** is still only a warning: the generator returns and writes nothing.
+
+**Warned about and left out, not refused**: a route with no method or path (reachable by
+registering a route before `.handler()` was called), and a router entry that is neither a
+route nor a router. `registerRoutes` warns and skips both, so a map without them still names
+every route the server answers — which is all a refusal would have been protecting.
+
+What a *package* router carries is never refused — an entry the app developer cannot fix
+is skipped, exactly as `registerRoutes` skips it.
 
 ### Generated output
 
@@ -199,10 +272,10 @@ generator's own surface.
 
 | | `route-map` | `contract` |
 |---|---|---|
-| Reads the router by | parsing the source | **loading the module** and walking `RouteDef`s |
+| Reads the router by | loading the module and walking `RouteDef`s | the same |
 | Covers | every registered route | only routes carrying `.contract()` |
 | `runOn` | `watch`, `manual`, `build` | `watch`, `build`, `manual` |
-| Can fail a build | no | **yes**, on the `build` trigger only |
+| Can fail a build | **yes** — any refusal, on every trigger the CLI fails on | **yes**; a broken contract only on the `build` trigger |
 
 Loading rather than parsing is what makes the contract correct: real routes build schemas from
 imported values (`EmailSchema`, `FileSchema()`, constants) that a source parser cannot resolve. It
@@ -216,8 +289,10 @@ costs a module import and no infrastructure — `@spfn/auth`'s 43 routes load in
 - No router export is found under the configured or default names.
 - Two contracted routes share a name, or a contracted route has no method, path, `since` or
   `response`.
-- `defineRouter({...})` contains a computed spread (`...(flag ? { route } : {})`), which would make
-  the contract describe whichever way the generator happened to run.
+- The router the generator was pointed at contains a conditional spread
+  (`...(flag ? { route } : {})`), which would make the contract describe whichever way the
+  generator happened to run. Same guard as `route-map` — see its bullet for exactly what is
+  scanned and what is allowed.
 - On the `build` trigger only: the contract breaks the newest released snapshot.
 
 `spfn dev` generates but never refuses — being unable to hold a half-finished route mid-edit would
@@ -232,7 +307,7 @@ Provided by the `spfn` CLI (`@spfn/cli`), not by `@spfn/core` itself:
 ```bash
 spfn codegen init     # scaffold a .spfnrc.ts
 spfn codegen list     # list resolved generators + their watch patterns  (alias: ls)
-spfn codegen run      # run all generators once (CodegenOrchestrator.generateAll, trigger 'manual')
+spfn codegen run      # run all generators once (CodegenOrchestrator.generateAll, trigger 'manual'; a failure exits 1)
 spfn dev              # dev server + codegen in watch mode
 spfn build            # runs codegen once before building (trigger 'build'; a failure exits 1)
 
@@ -245,6 +320,11 @@ spfn contract list       # released snapshots  (alias: ls)
 (The `spfn init` project scaffold writes a `.spfnrc.ts` preconfigured with the route-map
 generator and adds a `"codegen": "spfn codegen run"` npm script.)
 
+`spfn codegen run` **exits 1 when a generator refuses**, and stops at the one that refused
+— the run that just failed to regenerate a map must not look like the run that did. `spfn
+dev` is unaffected: watch mode logs the failure and keeps going, because being unable to
+hold a half-finished route mid-edit would make the feature unusable.
+
 ---
 
 ## Programmatic usage
@@ -405,11 +485,26 @@ regeneration when it's absent (build/manual passes don't set it).
   wrong (or no) `method`/`path`. `spfn build` runs codegen first; if you build by other
   means, run `spfn codegen run` yourself. Treat the file as generated (it's marked
   `DO NOT EDIT`).
-- **route-map only matches a specific route syntax.** Routes must be
-  `export const x = route.<method>('<literal path>')`. Dynamic paths, methods other than
-  get/post/put/patch/delete, or routes not listed in `defineRouter({...})` won't appear.
 - **A route must be in `defineRouter({...})` to be emitted.** Defining `export const foo =
-  route.get(...)` but not registering `foo` in the router drops it from the map.
+  route.get(...)` but not registering `foo` in the router drops it from the map — the
+  generator walks the router, so an unregistered route does not exist as far as it is
+  concerned. How the registration is *spelled* no longer matters.
+- **route-map loads your router, so route modules must import cleanly.** Reading a
+  required environment value at module scope now fails `spfn build` and `spfn codegen run`,
+  not just `spfn dev`. Move that read inside the handler. Top-level `await` in a route or
+  router module does not load either — jiti transforms to CJS — the same limit
+  `@spfn/core:contract` has always had.
+- **A path alias resolves only if a tsconfig between the router and the project root maps
+  it.** Both loading generators read `compilerOptions.paths` from the nearest such
+  `tsconfig.json` (following `extends`) and hand it to jiti, so `@/server/routes/users`
+  resolves from the root config or from `src/server/tsconfig.json`. A mapping that lives
+  *above* the project root — a monorepo's solution-style config — is not read; a `paths`
+  entry whose `*` is not a trailing `/*` is skipped (jiti matches a prefix, not a template);
+  and a `baseUrl` with no `paths` resolves nothing (an alias map cannot say "try this
+  directory for every bare specifier"). Several targets for one pattern are supported: the
+  first that exists on disk is used, as tsc and tsup use it. Each skip is warned about, an
+  `extends` target TypeScript could not read is warned about instead of silently dropping
+  its `paths`, and an import that then fails to resolve names the specifier.
 - **Custom generators must default-export a factory.** `createGeneratorsFromConfig` calls
   `module.default()` (a zero-arg function) for `{ path }` entries. Exporting the Generator
   object directly, or a factory that needs args, won't load.
@@ -505,12 +600,12 @@ interface RouteMapGeneratorConfig
     name: '@spfn/core:route-map';
     routerPath: string;
     outputPath?: string;               // default './src/generated/route-map.ts'
-    additionalRouteDirs?: string[];
+    additionalRouteDirs?: string[];   // deprecated: watched, never collected from
 }
 ```
 
 ## Related
 
-- [@spfn/core/route](../route/README.md) — `route.*` / `defineRouter` (the source parsed)
+- [@spfn/core/route](../route/README.md) — `route.*` / `defineRouter` (the router loaded and walked)
 - [@spfn/core/nextjs](../nextjs/README.md) — RPC proxy (`createRpcProxy`) that consumes `routeMap`
 - [@spfn/core/env](../env/README.md) — environment configuration

package/src/contract/README.md

@@ -285,7 +285,13 @@ JSON body and upload the file through its own uncontracted route.
   generator refuses a `defineRouter({...})` containing a computed spread (`...(flag ? {x} : {})`);
   a spread of a plain identifier (`...baseRoutes`) is fine.
 - **`NODE_ENV` is pinned when unset.** The generator sets it to `production` before loading, so a
-  schema that reads the environment cannot make the contract depend on the shell it ran in.
+  schema that reads the environment cannot make the contract depend on the shell it ran in. The pin
+  is process-wide and shared with `@spfn/core:route-map`, so both generators in one run read the
+  same environment whichever `.spfnrc.ts` lists first.
+- **Path aliases come from the project root's `tsconfig.json`.** `compilerOptions.paths` is read
+  (`extends` followed) and handed to jiti, so a router importing `@/server/routes/users` loads. A
+  mapping held in any other tsconfig is not read, and the failure names the specifier that did not
+  resolve.
 - **A failed build still rewrites `current.json`.** That is deliberate — the regenerated file is
   what the gate compared, so `git diff` shows exactly what broke.
 - **Constraint changes count as type changes.** Narrowing `maxLength`, an `enum` or a `format` is

package/src/nextjs/README.md

@@ -122,8 +122,28 @@ const created = await api.createUser.call({ body: { name: 'A' } }); // POST /api
 function createApi<TRouter extends Router<any>>(config?: ApiConfig): Client<TRouter>;
 ```
 
-Returns a `Proxy`: every property access (`api.getUser`, `api.foo.bar` for nested routers)
-yields a `RouteClient` builder. Calls are made via `.call(input)`.
+Returns a `Proxy`: every property access (`api.getUser`) yields a `RouteClient` builder.
+Calls are made via `.call(input)`.
+
+The client is one **flat** namespace, holding exactly the names the server registers. A
+route declared inside a nested `defineRouter` is reached by its own key — `registerRoutes`
+mounts it under that key, the proxy resolves that name against the route map, and
+`RouterOutput` takes the same name:
+
+```typescript
+const appRouter = defineRouter({
+    getRoot,
+    users: defineRouter({ getUser }),
+});
+
+await api.getUser.call({ params: { id: '123' } });   // ✅ GET /api/rpc/getUser
+await api.users.getUser.call({ ... });               // ❌ compile error — `users` is a group
+```
+
+There is no dot notation: a property access never yields another proxy, so a group key
+names nothing on either side. A name two branches both declare is left out of the client
+rather than resolved to one of them, and `.packages()` routes stay out on purpose — call
+them through the package's own client (`authApi`, `cmsApi`).
 
 ### Structured input
 
@@ -452,6 +472,27 @@ type BodyInput   = RouterInput<AppRouter, 'createExample'>['body'];
 `InferRouteOutput` take a single `RouteDef`. All inference is compile-time only (zero runtime
 cost).
 
+The route-name key is the **flat** set of names in the router tree. A route declared inside a
+nested `defineRouter` is named by its own key here, exactly as the server registers it — the
+group key is not part of the name and does not appear:
+
+```typescript
+const appRouter = defineRouter({
+    getRoot,
+    examples: defineRouter({ listExamples, createExample }),
+});
+
+type ListData = RouterOutput<typeof appRouter, 'listExamples'>;   // not 'examples.listExamples'
+```
+
+A name two branches both declare is left out of that set rather than resolved to one of them,
+so naming it is a compile error where it is named. Routes mounted with `.packages()` stay out
+of the set on purpose — call them through the package's own client.
+
+`Client<AppRouter>` — what `createApi` returns — is built from the same flat set, so a route
+is named identically whether you call it (`api.listExamples`) or take its type
+(`RouterOutput<AppRouter, 'listExamples'>`).
+
 ---
 
 ## Error handling

package/src/route/README.md

@@ -435,6 +435,12 @@ export const appRouter = defineRouter({ ...userRoutes, ...postRoutes });
 export type AppRouter = typeof appRouter;
 ```
 
+Nesting groups the source, not the name: a nested route is registered — and typed, through
+`RouterOutput`/`RouterInput` and the `createApi` client — under its own key (`get`, `list`),
+never under `users.get`. `api.get.call({...})` is the call; `api.users` is not a route and
+does not compile. Two branches declaring one name is therefore a collision, which the contract
+collector refuses and the client types leave out of the namespace.
+
 ### `.packages([...])` — mount package routers
 
 Attach routers from SPFN packages (`@spfn/auth`, `@spfn/cms`, …). Package routes **are**
@@ -452,6 +458,20 @@ export const appRouter = defineRouter({ getRoot, getStatus })
 
 `.packages()` also flattens any nested package routers the given routers themselves declared.
 
+**A name a package route already uses is not available to an app route.** Both register, at
+their own paths, and the app's proxy merges the two maps as `{ ...routeMap, ...authRouteMap }`
+— so the package entry wins the name while the generated types still describe the app's
+route. `spfn codegen run` refuses rather than generating that, naming both sides.
+
+A package that publishes **no** route map is the exception, and declares itself one with
+`defineUnmappedRouter`: its routes are reached by the URL something was handed rather than by
+name, so nothing merges over the app's map and an app route may share a name with one of them
+freely. `createOpsRouter` builds the ops surface that way — `spfn ops` invokes a command over
+its URL — as do `@spfn/monitor`, `@spfn/cms` and the tracking routes of `@spfn/notification`.
+`defineRouter` is the default because the obligation runs the other way: a package that does
+publish a map must not declare itself unmapped, or a collision that really would overwrite an
+app route generates silently.
+
 ### `.use([...])` — router-level global middleware
 
 Named middleware applied to **every** route in the router (and package routers), unless a