@ultimat3/action 22.14.0 → 23.0.0

package/CLAUDE.md

@@ -18,11 +18,13 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `facade.ts` | the fluent surface — binds each projection to the action, re-implements none |
 | `mutator.ts` | action + optimistic `.local` twin + authoritative `.server` + `.conflict` |
 | `registry.ts` | export-name registration, collisions, `describeActions()` |
-| `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call |
+| `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call, and the `Api` type the typed clients are shaped from |
+| `client-scale-pins.ts` | compile-time pin: `rpc<Api['actions']>` over 300 actions in 100 modules, 100 reads in 50 |
 | `http.ts` | route projection (`enforcedBy: 'handler'`) + OpenAPI operation |
 | `openapi.ts` | deterministic OpenAPI 3.1 document |
 | `openapi-complete.ts` | the COMPLETE document (`defineApi({ openapi })`: info, servers, security schemes, 401/429 by the ROUTE's `meta.auth`) and a bearer mount's own cut |
 | `http-path.ts` | where an action is served: the app's `pathStyle` + a per-action `http.path` pin, read lazily by every projection |
+| `path-style-miss.ts` | `explainActionPathMiss` — `@ultimat3/http`'s `hooks.explainMiss`: a POST under the style this app does not serve is `X_CONTRACT_DRIFT` naming the one it does |
 | `api-declaration.ts` | `defineApi({ http, openapi })` held process-wide for the boot and `x manifest` |
 | `errors-http.ts` | the three HTTP-declaration refusals (codes registered in `errors.ts`) |
 | `client.ts` | typed RPC client (browser-safe: no server imports) — dispatches through core's `clientTransport` |
@@ -77,8 +79,21 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   `'resource'` stays the default (changing it moves every URL). `defineApi` sets the style FIRST and
   `configureActionPathStyle` re-derives every seated action (the module scan may have seated them
   under the default). `derivePath(name)` is pin-aware through `installPinLookup` — handed down by
-  `registry.ts`, never imported up (cycle through `action.ts`). `rpc()` cannot see a pin: it takes
-  `pathStyle`; `action.client()` holds the pin.
+  `registry.ts`, never imported up (cycle through `action.ts`). `rpc()` cannot see a pin;
+  `action.client()` holds it.
+- **The style is stated ONCE, on the server.** A browser never restates it: the document carries
+  `<meta name="ultimate-path-style">` (render's `clientPathStyleTags`, written only for a
+  non-default style) and core's `actionPath(name)` reads it for every caller naming none — `rpc`,
+  realtime's `useMutation` and the outbox replay. `client.ts` passes `options.pathStyle` through
+  and adds NO default of its own. `ClientOptions.pathStyle` is for a caller with no document; a
+  wrong one is answered `X_CONTRACT_DRIFT` (404) by `explainActionPathMiss`, never
+  `X_ROUTE_NOT_FOUND`. A pinned action and a path under the SERVED style are never explained.
+- **`Merge` in `define-api.ts` never recurses over the module list.** `Head & Merge<Rest>` is not
+  a tail call: it cost one instantiation level per MODULE and answered TS2589 at the 48th entry of
+  one list, whatever each exported (#534). The list is read as a union and intersected in one
+  step. `client-scale-pins.ts` is the build error; `client-scale.contract.test.ts` compiles real
+  `action()`/`query()` modules through `defineApi`'s `const` inference; `@ultimat3/query` pins
+  `QueryClient` itself.
 - **`defineApi({ openapi })` opts into the complete document; absent, `openapi.json`'s bytes are
   unchanged** — an upgrade must not make a committed contract stale by itself.
 - Registration names the action the app exported, in place. Naming an already-named action is the
@@ -168,7 +183,9 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
   | `rpc` | 18,097 B | 23,007 B | 18,119 B | 19,074 B |
   | `rpc` + `createClientFlight` | 23,903 B | 28,823 B | not measured | 25,197 B |
 
-  Net against the pre-transport figure: +977 B, about the envelope decoder's size.
+  Net against the pre-transport figure: +977 B, about the envelope decoder's size. `As of 2026-10-01`
+  `rpc` is 19,671 B (19,490 B before the document's path-style stamp was read: +181 B, +45 gzipped)
+  and `rpc` + `createClientFlight` 25,954 B.
 - **The `sideEffects` array is load-bearing**: `errors.ts` runs `registerErrorCodes` at import. Never `false`.
 
 ## Invariants — idempotency

package/README.md

@@ -113,8 +113,10 @@ export const client = rpc<Api['actions']>({ baseUrl: '/' });
 ```
 
 `Api['actions']` is the merged module type, so `client.publishPost` is typed from the
-declaration with no codegen step. `Api` is imported as a **type only**, which is what keeps
-a page's module graph free of any edge to a feature's implementation.
+declaration with no codegen step — at any app size: `client-scale-pins.ts` compiles the idiom over
+300 actions in 100 modules on every `typecheck` (the limit was 47 modules in one list, #534).
+`x new` writes this file as `apps/web/shared/browser-client.ts`. `Api` is imported as a **type
+only**, which is what keeps a page's module graph free of any edge to a feature's implementation.
 
 Every call dispatches through `@ultimat3/core`'s `clientTransport` — the one browser HTTP function.
 It owns credentials, the JSON body, the `Idempotency-Key` header, the principal fence and the
@@ -157,8 +159,8 @@ await api.charge({ orderId }, { idempotencyKey: `charge:${orderId}`, retry: { at
 It shipped as a byte-identical copy in each; the copies are gone and every name is importable from
 this package exactly as before.
 
-Importing `rpc` alone from this package is **23,007 B** minified for the browser; adding
-`createClientFlight` is **28,823 B** (`As of 2026-09-22`; `CLAUDE.md` carries the before/after and
+Importing `rpc` alone from this package is **19,671 B** minified for the browser; adding
+`createClientFlight` is **25,954 B** (`As of 2026-10-01`; `CLAUDE.md` carries the before/after and
 what the delta is). `ClientFlight` is a TYPE inside `client.ts` and never a value, which is what
 keeps the second number off the first caller's bill.
 
@@ -182,9 +184,15 @@ One rule per app, declared once — `defineApi({ http: { pathStyle } })` — plu
   `/_x` (`X_ACTION_HTTP_PATH_INVALID`). A pin colliding with another path is
   `X_ACTION_PATH_DUPLICATE` at boot.
 - Every server-side reader agrees: `toRoute`, `toOpenApiOperation`, `describeAction`,
-  `derivePath(name)` (pin-aware) and `actionHttpPath(action | name)`. The browser's `rpc()` derives
-  from the name alone, so it is told the style: `rpc({ baseUrl, pathStyle: 'readable' })`; a pinned
-  action is called through `action.client()`, which holds the pin.
+  `derivePath(name)` (pin-aware) and `actionHttpPath(action | name)`. A pinned action is called
+  through `action.client()`, which holds the pin.
+- **A browser states no style.** The server stamps a non-default one into every document
+  (`<meta name="ultimate-path-style">`) and `rpc({ baseUrl: '' })` derives under it — as do
+  `useMutation` and the outbox replay. `'resource'` writes no tag.
+- **A caller with no document passes it**: `rpc({ baseUrl, pathStyle: 'readable' })` in a script or
+  another service. The wrong one is answered by the server — 404 `X_CONTRACT_DRIFT`, naming the
+  style it serves and the path the action lives at — never a bare `X_ROUTE_NOT_FOUND`
+  (`explainActionPathMiss`, wired as `@ultimat3/http`'s `hooks.explainMiss`).
 - **The style is read when the path is derived, so derive it late.** The scan evaluates
   `apps/web/api/index.ts` before any other module, so a page or admin view already sees the declared
   style. A module the index itself imports runs before its `defineApi` call: a module-level

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.14.0",
+  "version": "23.0.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -22,6 +22,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -34,11 +35,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.14.0",
-    "@ultimat3/core": "22.14.0",
-    "@ultimat3/entity": "22.14.0",
-    "@ultimat3/http": "22.14.0",
-    "@ultimat3/policy": "22.14.0",
-    "@ultimat3/schema": "22.14.0"
+    "@ultimat3/cache": "23.0.0",
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/entity": "23.0.0",
+    "@ultimat3/http": "23.0.0",
+    "@ultimat3/policy": "23.0.0",
+    "@ultimat3/schema": "23.0.0"
   }
 }

package/src/client-scale-pins.ts

@@ -0,0 +1,126 @@
+// Compile-time pin: the documented `rpc<Api['actions']>` idiom at 300 actions in 100 modules.
+// Source, not a `.test.ts`, for `type-pins.ts`'s reason — `tsc -b` never reads a test file. Types
+// only: nothing here is emitted, and a regression is TS2589 in the `typecheck` step.
+//
+// The shape is the OBSERVED one (issue #534): the limit was never the action count, it was the
+// number of MODULES in one `defineApi` list — 47 passed and 48 failed, whatever they exported.
+
+import type { NumberSchema, ObjectSchema, StringSchema } from '@ultimat3/schema';
+import type { Action } from './action';
+import type { rpc } from './client';
+import type { defineApi } from './define-api';
+
+type Assert<T extends true> = T;
+
+type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+type Verb = 'create' | 'update' | 'archive';
+
+/** Distinct per module (`m7`), so no two modules collapse into one instantiation. */
+type ScaleInput<N extends number> = ObjectSchema<
+  {
+    readonly id: StringSchema;
+    readonly title: StringSchema;
+    readonly nested: ObjectSchema<{ readonly label: StringSchema; readonly rank: NumberSchema }>;
+  } & { readonly [K in `m${N}`]: NumberSchema }
+>;
+
+type ScaleOutput<N extends number> = ObjectSchema<
+  { readonly id: StringSchema } & { readonly [K in `out${N}`]: StringSchema }
+>;
+
+/** A feature module as `import * as` sees one: its actions, and a helper that is not one. */
+type ActionModule<N extends number> = {
+  readonly [K in `${Verb}Thing${N}`]: Action<ScaleInput<N>, ScaleOutput<N>>;
+} & { readonly [K in `helper${N}`]: (value: number) => number };
+
+/** `@ultimat3/query` is sideways, so a read is stood in for by the two members `Merge` reads. */
+type QueryModule<N extends number> = {
+  readonly [K in `listRows${N}` | `oneRow${N}`]: { readonly kind: 'query'; readonly name: string };
+};
+
+/** `[Module<0>, …, Module<TCount - 1>]`. A tail call, so the list length costs no depth here. */
+type ActionModules<
+  TCount extends number,
+  TAcc extends readonly unknown[] = [],
+> = TAcc['length'] extends TCount
+  ? TAcc
+  : ActionModules<TCount, [...TAcc, ActionModule<TAcc['length']>]>;
+
+type QueryModules<
+  TCount extends number,
+  TAcc extends readonly unknown[] = [],
+> = TAcc['length'] extends TCount
+  ? TAcc
+  : QueryModules<TCount, [...TAcc, QueryModule<TAcc['length']>]>;
+
+/** 100 modules of 3 actions, 50 modules of 2 reads — through `defineApi`'s own signature. */
+type ScaleApi = ReturnType<
+  typeof defineApi<{
+    readonly actions: ActionModules<100>;
+    readonly queries: QueryModules<50>;
+  }>
+>;
+
+/** The idiom itself: its `ActionMap` constraint is where TS2589 was raised. */
+type ScaleClient = ReturnType<typeof rpc<ScaleApi['actions']>>;
+
+export type _EveryModuleReachesTheClient = Assert<
+  'createThing0' | 'updateThing47' | 'archiveThing99' extends keyof ScaleClient ? true : false
+>;
+
+/** 300, counted: a `Merge` that dropped a module would still pass the three names above. */
+export type _TheClientHasExactlyTheRegisteredActions = Assert<
+  Equals<keyof ScaleClient, ActionName>
+>;
+
+type ActionName = {
+  [N in keyof ActionModules<100> & `${number}`]: `${Verb}Thing${N}`;
+}[keyof ActionModules<100> & `${number}`];
+
+/** A helper exported beside the actions is not a method — the server never registered it. */
+export type _AHelperIsNotAClientMethod = Assert<'helper0' extends keyof ScaleClient ? false : true>;
+
+/** One call, both sides inferred from the LAST module's own schemas. */
+export type _TheLastActionKeepsItsInput = Assert<
+  Equals<
+    Parameters<ScaleClient['archiveThing99']>[0],
+    {
+      readonly id: string;
+      readonly title: string;
+      readonly nested: { readonly label: string; readonly rank: number };
+      readonly m99: number;
+    }
+  >
+>;
+
+export type _TheLastActionKeepsItsOutput = Assert<
+  Equals<
+    Awaited<ReturnType<ScaleClient['archiveThing99']>>,
+    { readonly id: string; readonly out99: string }
+  >
+>;
+
+/** `Api['queries']` is the same `Merge`, and regresses with it. */
+export type _EveryQueryModuleIsMerged = Assert<
+  Equals<
+    keyof ScaleApi['queries'],
+    {
+      [N in keyof QueryModules<50> & `${number}`]: `listRows${N}` | `oneRow${N}`;
+    }[keyof QueryModules<50> & `${number}`]
+  >
+>;
+
+/** No list at all, and an empty one, are both the empty map — never `unknown`. */
+type EmptyApi = ReturnType<typeof defineApi<{ readonly actions: readonly [] }>>;
+
+export type _AnEmptyListIsAnEmptyMap = Assert<
+  Equals<keyof EmptyApi['actions'] | keyof EmptyApi['queries'], never>
+>;
+
+export type _AnEmptyMapStillSatisfiesRpc = ReturnType<typeof rpc<EmptyApi['actions']>>;
+
+/** One module handed over bare, not in a list — the other spelling `ApiModules` allows. */
+type BareApi = ReturnType<typeof defineApi<{ readonly actions: ActionModule<7> }>>;
+
+export type _ABareModuleIsRegisteredToo = Assert<Equals<keyof BareApi['actions'], `${Verb}Thing7`>>;

package/src/client.ts

@@ -84,10 +84,13 @@ export interface ClientOptions {
    */
   readonly flight?: ClientFlight;
   /**
-   * The server's `defineApi({ http: { pathStyle } })`, restated: the browser derives each URL from
-   * the name and cannot read the server's registry. Absent is `'resource'`, the server's default.
-   * A per-action `http.path` pin is honoured by `action.client()` (it holds the declaration); the
-   * name-only `rpc()` proxy cannot see one, so a pinned action is called through its own client.
+   * The style of a server that is NOT the one that rendered this page — a script, another
+   * service. A browser states nothing: the server stamps its `defineApi({ http: { pathStyle } })`
+   * into the document and every path is derived under that. With no document and no value here it
+   * is `'resource'`, the server's default; a server reached under the wrong one answers
+   * `X_CONTRACT_DRIFT` naming the style it serves. A per-action `http.path` pin is honoured by
+   * `action.client()` (it holds the declaration); the name-only `rpc()` proxy cannot see one, so a
+   * pinned action is called through its own client.
    */
   readonly pathStyle?: ActionPathStyle;
 }
@@ -123,7 +126,9 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
   options: ClientOptions,
   pinnedPath?: string,
 ): ClientMethod<TInput, TOutput> {
-  const path = pinnedPath ?? actionPath(name, options.pathStyle ?? 'resource');
+  // No default here: for a caller naming no style, `actionPath` asks the document the server
+  // rendered, and that answer must be the same one `useMutation` and the outbox replay get.
+  const path = pinnedPath ?? actionPath(name, options.pathStyle);
   const url = `${options.baseUrl.replace(/\/+$/, '')}${path}`;
   const onResponse = (response: Response): void =>
     assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);

package/src/define-api.ts

@@ -50,16 +50,28 @@ type Registered<TModule, TKind extends string> = {
 };
 
 /**
- * Intersect a tuple of module namespaces. `{ createPost } & { inviteMember }` is the map the
+ * Intersect a list of module namespaces. `{ createPost } & { inviteMember }` is the map the
  * typed client indexes, so `rpc<Api['actions']>()` knows every action without a codegen step.
+ *
+ * Never by recursion over the tuple. `Registered<Head> & Merge<Rest>` is not a tail call, so the
+ * compiler spent one level of its instantiation depth per MODULE and answered TS2589 at the 48th
+ * entry of one list — whatever the number of actions inside them (measured: 30 modules of 10 pass,
+ * 48 modules of 1 fail). The list is read as a union and intersected in one step, so the depth is
+ * constant and `client-scale-pins.ts` holds it there.
  */
 type Merge<TModules, TKind extends string> = [TModules] extends [undefined]
   ? EmptyModule
-  : TModules extends readonly [infer THead, ...infer TRest]
-    ? Registered<THead, TKind> & Merge<TRest, TKind>
-    : TModules extends readonly []
-      ? EmptyModule
-      : Registered<TModules, TKind>;
+  : TModules extends readonly unknown[]
+    ? MergeAll<TModules[number], TKind>
+    : Registered<TModules, TKind>;
+
+/** An empty list has no members to intersect — and `unknown` is not a map `rpc` accepts. */
+type MergeAll<TModule, TKind extends string> = [TModule] extends [never]
+  ? EmptyModule
+  : Intersect<TModule extends unknown ? (map: Registered<TModule, TKind>) => void : never>;
+
+/** A union of one-parameter functions infers that parameter as the intersection of them all. */
+type Intersect<TFns> = [TFns] extends [(map: infer TMap) => void] ? TMap : never;
 
 type EmptyModule = Readonly<Record<never, never>>;
 

package/src/index.ts

@@ -237,6 +237,11 @@ export {
   completeOpenApi,
   mountOpenApi,
 } from './openapi-complete';
+/**
+ * `@ultimat3/http`'s `hooks.explainMiss` for the action surface: a POST to an action's path under
+ * a `pathStyle` this app does not serve answers `X_CONTRACT_DRIFT` naming the style it does.
+ */
+export { explainActionPathMiss } from './path-style-miss';
 export type { ActionPolicy, PolicySubject, Surface } from './policy-gate';
 /**
  * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.

package/src/path-style-miss.ts

@@ -0,0 +1,56 @@
+/**
+ * What the server says to a caller that derived an action's URL under the WRONG path style: a
+ * script or another service passing `rpc({ pathStyle })` by hand, where matching build ids prove
+ * nothing. Handed to `@ultimat3/http` as `hooks.explainMiss`, so it runs only when the router
+ * matched nothing — and answers `X_CONTRACT_DRIFT` naming the style served, in place of a
+ * `X_ROUTE_NOT_FOUND` that sends the caller looking for a route that exists.
+ */
+
+import type { ActionPathStyle } from '@ultimat3/core';
+import { ACTION_PATH_PREFIX, ACTION_PATH_STYLES, actionRoute } from '@ultimat3/core';
+import { ContractDriftError } from './errors';
+import { actionPathStyle, servedActionRoute } from './http-path';
+import { defOf } from './invoke';
+import { seatedActions } from './registry-store';
+
+/**
+ * The action `pathname` names under a style this app does not serve, or `undefined`. A pinned
+ * action is skipped: its URL is the pin under every style, so no style explains missing it.
+ *
+ * A walk of the registry per miss, and deliberately not an index: the registry and the style both
+ * move (`x dev` re-evaluates modules), and only a POST under `/api/` that matched no route pays —
+ * one string derivation per action, no I/O.
+ */
+function driftedAction(
+  pathname: string,
+): { readonly name: string; readonly under: ActionPathStyle } | undefined {
+  const served = actionPathStyle();
+  for (const under of ACTION_PATH_STYLES) {
+    if (under === served) continue;
+    // why no index: a memo keyed by path would outlive a re-registration and name a stale action.
+    for (const [name, seated] of seatedActions) {
+      if (defOf(seated).http?.path !== undefined) continue;
+      if (actionRoute(name, under).path === pathname) return { name, under };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * `hooks.explainMiss` for the action surface. Every value in the message is the framework's own:
+ * the name is a registered export name and both paths are derived from it — the caller's bytes
+ * reach the message only by being equal to one of them.
+ */
+export function explainActionPathMiss(
+  method: string,
+  pathname: string,
+): ContractDriftError | undefined {
+  if (method !== 'POST' || !pathname.startsWith(`${ACTION_PATH_PREFIX}/`)) return undefined;
+  const drifted = driftedAction(pathname);
+  if (drifted === undefined) return undefined;
+  const served = actionPathStyle();
+  return new ContractDriftError(
+    `POST ${pathname} is ${drifted.name} under pathStyle '${drifted.under}'; this server serves pathStyle '${served}', where it is POST ${servedActionRoute(drifted.name).path}`,
+    `rpc<Api['actions']>({ baseUrl, pathStyle: '${served}' })   # in a browser, pass no pathStyle: the page states it`,
+  );
+}