@ultimat3/action 22.5.1 → 22.6.1

package/CLAUDE.md

@@ -21,6 +21,10 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 | `define-api.ts` | `defineApi({ actions, mutators, queries, llm, jobs, tasks })` — the app's one boot call |
 | `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 |
+| `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` |
 | `record-wire.ts` | the record envelope on the HTTP projection: `carriesRecords` (from the output schema), the enveloped 200, and its OpenAPI shape. Server-only — `client.ts` never imports it |
 | `wire-issues.ts` | the ONE reader of a problem document's `issues` member — an untrusted array back into `@ultimat3/schema`'s `ValidationIssue` shape |
@@ -68,6 +72,14 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 - No policy at registration → `X_ACTION_POLICY_MISSING`. No exceptions, no flag.
 - **`registerAction` guards the derived PATH as well as the name** (`X_ACTION_PATH_DUPLICATE`; a
   second index cleared by `resetRegistry`).
+- **A path is the app's `pathStyle` or the action's pin, never a third answer** (`http-path.ts`).
+  `'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.
+- **`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
   only case that twins.
 - A mutator projects `.local`, `.server`, `.conflict` plus every action member — no aliases.

package/README.md

@@ -164,10 +164,77 @@ keeps the second number off the first caller's bill.
 
 ## Path derivation
 
-First camelCase word is the verb; the rest is the resource, last word pluralized,
-kebab-cased. The **MCP tool name is not derived at all** — it is the export name verbatim, because
+One rule per app, declared once — `defineApi({ http: { pathStyle } })` — plus a per-action pin.
+
+| `pathStyle` | `publishPost` | `signIn` | `health` | `viewCustomer360` |
+|---|---|---|---|---|
+| `'resource'` (default) | `/api/posts/publish` | `/api/ins/sign` | `/api/healths/invoke` | `/api/customer360s/view` |
+| `'readable'` | `/api/publish-post` | `/api/sign-in` | `/api/health` | `/api/view-customer360` |
+
+- **`'resource'`** guesses a noun from the words after the first and pluralizes it — right for
+  `verbNoun`, ungrammatical otherwise. It stays the default: changing it moves every URL an app
+  serves, so an app opts in.
+- **`'readable'`** guesses nothing: `/api/<kebab-cased export name>`, the rule `/_x/query/<kebab>`
+  follows for reads. The OpenAPI tag becomes the resource the POLICY names (`can('cases:create')`
+  → `cases`), never a noun parsed from `In`.
+- **`http: { path }` pins one action's URL** whatever the style — for a webhook a vendor holds:
+  `action({ …, http: { path: '/api/webhooks/wompi' } })`. Static, lowercase, no params, never
+  `/_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.
+- **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
+  `const SIGN_OUT = derivePath('signOut').path` there captures the default style, and the
+  declaration refuses the switch with `X_ACTION_PATH_DERIVED_EARLY`, naming it. Derive inside the
+  component or function instead.
+
+```ts
+import { defineApi } from '@ultimat3/action';
+import type { BearerResolver } from '@ultimat3/http';
+
+declare const resolveToken: BearerResolver; // the app's MCP token resolver
+declare const MCP_SCOPES: Readonly<Record<string, readonly string[]>>;
+
+export const api = defineApi({
+  // actions, queries, jobs, tasks — as always
+  http: {
+    pathStyle: 'readable',
+    // A second door onto a cut of the SAME routes: Authorization: Bearer only (a session cookie
+    // authenticates nothing there), 404 for a primitive outside the token's scopes, and a
+    // per-token allowance answered with RateLimit-* and 429 + Retry-After.
+    mounts: [{
+      prefix: '/v1',
+      scopes: MCP_SCOPES,            // scope -> [primitive names]; the map defineAppMcp takes
+      resolveToken,                  // the MCP resolver: token -> { actor, scopes } | null
+      rateLimit: { limit: 120, windowMs: 60_000 },
+      openapi: 'openapi.v1.json',    // x manifest writes only the cut here; x verify checks it
+    }],
+  },
+  // Declaring it (any key) makes openapi.json COMPLETE: info, servers, securitySchemes
+  // (cookie; bearer when a mount exists), 401 + 429 (Retry-After) on every authenticated
+  // operation, RateLimit-* on rate-limited ones. Absent, the bytes are what they were.
+  openapi: {
+    title: 'Notificado API',
+    version: '1.0.0',
+    servers: [{ url: 'https://www.notificado.co' }],
+    sessionCookie: 'session',
+  },
+});
+```
+
+`toPostBinding(action, path)` is the same projection bound to a PAGE's URL for `POST`, the URL's
+query merged over the posted fields (query wins): what `defineRoute({ post: '<action>' })` mounts,
+for an RFC 8058 one-click unsubscribe.
+
+The **MCP tool name is not derived at all** — it is the export name verbatim, because
 that is what `defineAppMcp`'s `scopes:` and a `tools/call` have to spell.
 
+Under the default style:
+
 | Action | Route | MCP tool |
 |---|---|---|
 | `publishPost` | `POST /api/posts/publish` | `publishPost` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.5.1",
+  "version": "22.6.1",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,11 +34,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.5.1",
-    "@ultimat3/core": "22.5.1",
-    "@ultimat3/entity": "22.5.1",
-    "@ultimat3/http": "22.5.1",
-    "@ultimat3/policy": "22.5.1",
-    "@ultimat3/schema": "22.5.1"
+    "@ultimat3/cache": "22.6.1",
+    "@ultimat3/core": "22.6.1",
+    "@ultimat3/entity": "22.6.1",
+    "@ultimat3/http": "22.6.1",
+    "@ultimat3/policy": "22.6.1",
+    "@ultimat3/schema": "22.6.1"
   }
 }

package/src/action.ts

@@ -14,13 +14,14 @@ import type { ContractTest, ContractTestOptions } from './contract-test';
 import type { Deprecation } from './deprecation';
 import { facadeFor } from './facade';
 import type { OpenApiOperation } from './http';
+import type { ActionHttp } from './http-path';
+import { routeFor } from './http-path';
 import type { IdempotencyStore } from './idempotency';
 import { actionName, defOf, hasDef, invoke, stashDef } from './invoke';
 import type { ActionJobHandle } from './job-handle';
 import type { JsonSchemaObject } from './json-schema';
 import { jsonSchemaOf } from './json-schema';
 import type { McpToolDescriptor } from './mcp-tool';
-import { derivePath } from './naming';
 import {
   type ActionPolicy,
   policyCapability,
@@ -91,6 +92,12 @@ export interface ActionDef<
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly rateLimit?: ActionRateLimit;
+  /**
+   * The HTTP projection's one per-action knob: `http: { path }` pins the URL whatever the app's
+   * `pathStyle` derives — for a webhook a vendor was given. Everything else about the route (the
+   * method, the policy, the body) stays the framework's.
+   */
+  readonly http?: ActionHttp;
   /**
    * On its way out. Declared here and projected everywhere at once: `Deprecation` and `Sunset`
    * response headers (RFC 9745 / RFC 8594), a `rel="successor-version"` link when `replacedBy`
@@ -203,6 +210,7 @@ export interface AnyActionDef {
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly rateLimit?: ActionRateLimit;
+  readonly http?: ActionHttp;
   readonly deprecated?: Deprecation;
   readonly idempotent?: boolean;
   readonly audit?: boolean;
@@ -329,7 +337,7 @@ function build<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1
 export function describeAction(target: AnyAction): ActionDescriptor {
   const name = actionName(target);
   const def = defOf(target);
-  const path = derivePath(name);
+  const path = routeFor(name, def.http?.path);
   const mcp = def.mcp;
   return {
     kind: 'action',

package/src/api-declaration.ts

@@ -0,0 +1,123 @@
+/**
+ * What an app says about its API as a WHOLE, beside the primitives it registers: how action names
+ * become URLs, which bearer-token mounts expose a cut of it, and what its OpenAPI document calls
+ * itself. Declared in the one `defineApi()` call and held here, process-wide like the registries,
+ * because every reader — the boot that mounts routes, `x manifest` writing `openapi.json` — runs
+ * after that module was imported and never has the call's return value in hand.
+ */
+
+import type { ActionPathStyle } from '@ultimat3/core';
+import type { BearerMountRateLimit, BearerResolver } from '@ultimat3/http';
+import { OpenApiConfigInvalidError } from './errors-http';
+
+/** A second door onto a cut of the API, authenticated by `Authorization: Bearer` alone. */
+export interface ApiMount {
+  /** `'/v1'`. The cut is served there: `POST /v1/create-case`, `GET /v1/case-list`. */
+  readonly prefix: string;
+  /**
+   * Scope → the actions and queries it covers, by export name — the map `defineAppMcp({ scopes })`
+   * takes, so one declaration governs both surfaces. Its union is the cut; a token sees a
+   * primitive only while it carries that primitive's scope, and anything else answers 404.
+   */
+  readonly scopes: Readonly<Record<string, readonly string[]>>;
+  /** The app's token resolver — the SAME function its MCP endpoint is given. */
+  readonly resolveToken: BearerResolver;
+  /** Requests per window per token, answered with `RateLimit-*` and a 429 + `Retry-After`. */
+  readonly rateLimit?: BearerMountRateLimit;
+  /**
+   * An app-root file this mount's OWN OpenAPI document is written to (`'openapi.v1.json'`): only
+   * the cut, at the mounted paths, under a `bearer` security scheme. `x manifest` writes it and
+   * `x verify` refuses it stale, exactly as it does `openapi.json`.
+   */
+  readonly openapi?: string;
+}
+
+export interface ApiHttp {
+  /** `'readable'`: `signIn` → `/api/sign-in`. Default `'resource'`: `/api/ins/sign`. */
+  readonly pathStyle?: ActionPathStyle;
+  readonly mounts?: readonly ApiMount[];
+}
+
+export interface OpenApiServer {
+  readonly url: string;
+  readonly description?: string;
+}
+
+/**
+ * Declaring this block — any key of it — opts the app's documents into the COMPLETE shape: its
+ * own `info`, `servers`, `components.securitySchemes`, and 401 / 429 problem responses on every
+ * authenticated operation. Absent, `openapi.json` keeps the bytes it had, so an upgrade does not
+ * turn an app's committed contract stale by itself.
+ */
+export interface ApiOpenApi {
+  /** `info.title`. Defaults to the app's name. */
+  readonly title?: string;
+  /** `info.version` — the API's contract version, not the app's build. Defaults to the app's. */
+  readonly version?: string;
+  readonly description?: string;
+  readonly servers?: readonly OpenApiServer[];
+  /** The session cookie the `cookie` security scheme names. Default `'session'`. */
+  readonly sessionCookie?: string;
+}
+
+export interface ApiDeclaration {
+  readonly http?: ApiHttp;
+  readonly openapi?: ApiOpenApi;
+}
+
+let declared: ApiDeclaration = {};
+
+const DOCUMENT_FILE = /^[A-Za-z0-9._-]+\.json$/;
+
+const isAbsoluteHttp = (url: string): boolean => {
+  const parsed = URL.parse(url);
+  return parsed !== null && (parsed.protocol === 'https:' || parsed.protocol === 'http:');
+};
+
+function assertOpenApi(openapi: ApiOpenApi | undefined, mounts: readonly ApiMount[]): void {
+  if (openapi !== undefined) {
+    for (const key of ['title', 'version'] as const) {
+      const value = openapi[key];
+      if (value !== undefined && (typeof value !== 'string' || value.trim() === '')) {
+        throw new OpenApiConfigInvalidError(`${key} is empty`);
+      }
+    }
+    for (const server of openapi.servers ?? []) {
+      if (!isAbsoluteHttp(server.url)) {
+        throw new OpenApiConfigInvalidError(
+          `server ${JSON.stringify(server.url)} is not an absolute http(s) URL`,
+        );
+      }
+    }
+  }
+  const files = new Set<string>(['openapi.json']);
+  for (const mount of mounts) {
+    if (mount.openapi === undefined) continue;
+    if (!DOCUMENT_FILE.test(mount.openapi) || files.has(mount.openapi)) {
+      throw new OpenApiConfigInvalidError(
+        `the ${mount.prefix} mount's document ${JSON.stringify(mount.openapi)} is not a distinct app-root .json file name`,
+      );
+    }
+    files.add(mount.openapi);
+  }
+}
+
+/** Called by `defineApi`. A later call replaces only the sections it declares. */
+export function declareApi(next: ApiDeclaration): void {
+  assertOpenApi(next.openapi, next.http?.mounts ?? []);
+  declared = {
+    ...declared,
+    ...(next.http === undefined ? {} : { http: next.http }),
+    ...(next.openapi === undefined ? {} : { openapi: next.openapi }),
+  };
+}
+
+/** What the app declared — `{}` for an app that declared nothing beyond its primitives. */
+export function apiDeclaration(): ApiDeclaration {
+  return declared;
+}
+
+/** Test seam, called by `resetRegistry`. */
+export function resetApiDeclaration(): void {
+  declared = {};
+}

package/src/client.ts

@@ -15,7 +15,13 @@
  * check (`onResponse`) and the action-named error decode (`decodeError`). The caller still gets exactly the action's output — the envelope
  * never reaches the return type.
  */
-import type { ClientFlight, ClientRetry, FetchLike, UltimateError } from '@ultimat3/core';
+import type {
+  ActionPathStyle,
+  ClientFlight,
+  ClientRetry,
+  FetchLike,
+  UltimateError,
+} from '@ultimat3/core';
 import {
   actionPath,
   clientTransport,
@@ -77,6 +83,13 @@ export interface ClientOptions {
    * nothing else, which is what every caller written before this option existed already gets.
    */
   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.
+   */
+  readonly pathStyle?: ActionPathStyle;
 }
 
 /**
@@ -108,8 +121,10 @@ export function rpc<TActions extends ActionMap>(options: ClientOptions): Client<
 export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
   name: string,
   options: ClientOptions,
+  pinnedPath?: string,
 ): ClientMethod<TInput, TOutput> {
-  const url = `${options.baseUrl.replace(/\/+$/, '')}${actionPath(name)}`;
+  const path = pinnedPath ?? actionPath(name, options.pathStyle ?? 'resource');
+  const url = `${options.baseUrl.replace(/\/+$/, '')}${path}`;
   const onResponse = (response: Response): void =>
     assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);
   const decodeError = (status: number, text: string): UltimateError | undefined =>

package/src/define-api.ts

@@ -6,7 +6,9 @@
  */
 
 import { type PrimitiveKind, primitiveRegistrar, type RegisteredPrimitive } from '@ultimat3/core';
-import { registerActions } from './registry';
+import type { ApiHttp, ApiOpenApi } from './api-declaration';
+import { declareApi } from './api-declaration';
+import { configureActionPathStyle, registerActions } from './registry';
 
 /** A module namespace: `import * as postActions from './actions'`. */
 export type ApiModule = Readonly<Record<string, unknown>>;
@@ -25,6 +27,13 @@ export interface ApiDef {
   readonly jobs?: ApiModules;
   /** A task only enqueues jobs; handing it over here is what names its cron after its export. */
   readonly tasks?: ApiModules;
+  /**
+   * The API's HTTP shape as a whole: `pathStyle` (how every action name becomes a URL) and
+   * `mounts` (bearer-token doors onto a cut of it, like `/v1`). Read by the boot and `x manifest`.
+   */
+  readonly http?: ApiHttp;
+  /** Declaring it opts `openapi.json` into the complete document — see `ApiOpenApi`. */
+  readonly openapi?: ApiOpenApi;
 }
 
 type Get<TDef, TKey extends string> = TKey extends keyof TDef ? TDef[TKey] : undefined;
@@ -82,6 +91,13 @@ export interface Api<TDef extends ApiDef> {
  * `@ultimat3/jobs` are on this tier and importing either sideways is a build error.
  */
 export function defineApi<const TDef extends ApiDef>(def: TDef): Api<TDef> {
+  // FIRST: the style decides every path the registrations below are checked against, and it
+  // re-derives the ones the framework's module scan may already have seated under the default.
+  if (def.http?.pathStyle !== undefined) configureActionPathStyle(def.http.pathStyle);
+  declareApi({
+    ...(def.http === undefined ? {} : { http: def.http }),
+    ...(def.openapi === undefined ? {} : { openapi: def.openapi }),
+  });
   const actionModules = [
     ...moduleList(def.actions),
     ...moduleList(def.mutators),

package/src/errors-http.ts

@@ -0,0 +1,67 @@
+/**
+ * The refusals of the HTTP declaration an app makes about its actions: a pinned `http.path`, the
+ * app's `pathStyle`, and the `openapi` block. Split from `errors.ts` at its ceiling; the codes and
+ * titles stay registered there, one registry.
+ */
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+
+export class ActionHttpPathInvalidError extends UltimateError {
+  constructor(input: { name: string; path: unknown; reason: string }) {
+    super({
+      code: 'X_ACTION_HTTP_PATH_INVALID',
+      cause: `action "${input.name}" pins http.path ${renderCauseValue(input.path)}, which ${input.reason}`,
+      fix: "pin a static lowercase path: http: { path: '/api/webhooks/wompi' } — a leading slash, segments of a-z 0-9 . _ ~ -, no :param or *wildcard, no trailing slash, never under /_x",
+      meta: { action: input.name },
+    });
+  }
+}
+
+export class ActionPathStyleInvalidError extends UltimateError {
+  constructor(value: unknown) {
+    super({
+      code: 'X_ACTION_PATH_STYLE_INVALID',
+      cause: `defineApi({ http: { pathStyle: ${renderCauseValue(value)} } }) is not 'resource' or 'readable'`,
+      fix: "defineApi({ ..., http: { pathStyle: 'readable' } }) — or omit it for 'resource', the default",
+    });
+  }
+}
+
+/**
+ * A path was handed out under one style and the app then declared another. The string is already
+ * captured — a module-level `const SIGN_OUT = derivePath('signOut').path` — so re-deriving the
+ * registry cannot reach it: that form would post to a URL no route serves. Refused at the
+ * declaration, naming every stale capture, rather than answered 404 in production.
+ */
+export class ActionPathDerivedEarlyError extends UltimateError {
+  constructor(input: {
+    readonly style: string;
+    readonly stale: readonly {
+      readonly name: string;
+      readonly was: string;
+      readonly now: string;
+    }[];
+  }) {
+    const shown = input.stale
+      .slice(0, 5)
+      .map((row) => `${row.name} (${row.was}, now ${row.now})`)
+      .join(', ');
+    const more = input.stale.length > 5 ? ` and ${input.stale.length - 5} more` : '';
+    super({
+      code: 'X_ACTION_PATH_DERIVED_EARLY',
+      cause: `pathStyle '${input.style}' was declared after a path was already derived under the previous style: ${shown}${more} — any module that kept that string holds a URL no route serves`,
+      fix: 'derive the path where it is used — inside the component or function, never in a module-level const — or import the module that calls defineApi({ http: { pathStyle } }) before the one that derives it',
+      meta: { style: input.style, names: input.stale.map((row) => row.name) },
+    });
+  }
+}
+
+export class OpenApiConfigInvalidError extends UltimateError {
+  constructor(reason: string) {
+    super({
+      code: 'X_OPENAPI_CONFIG_INVALID',
+      cause: `defineApi({ openapi }) cannot produce a valid document: ${reason}`,
+      fix: "defineApi({ ..., openapi: { title: 'My API', version: '1.0.0', servers: [{ url: 'https://www.example.com' }] } }) — non-empty title and version, absolute http(s) server URLs, and a mount document named like 'openapi.v1.json'",
+    });
+  }
+}

package/src/errors.ts

@@ -55,6 +55,10 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
     "a mutator declares conflict: 'last-write-wins' and its entity has no number clock column",
   X_OUTPUT_INVALID: 'a handler returned a value its output schema rejects',
   X_RPC_FAILED: 'an RPC call failed without a problem+json body',
+  X_ACTION_HTTP_PATH_INVALID: "an action's pinned http.path is not a static lowercase path",
+  X_ACTION_PATH_STYLE_INVALID: "defineApi's http.pathStyle is not a known style",
+  X_OPENAPI_CONFIG_INVALID: "defineApi's openapi block cannot produce a valid document",
+  X_ACTION_PATH_DERIVED_EARLY: 'a path was derived before pathStyle changed',
 };
 
 // One unconditional call: a presence guard would turn "another package claims one of these codes"

package/src/facade.ts

@@ -35,7 +35,7 @@ export function facadeFor<TInput extends StandardSchemaV1, TOutput extends Stand
       invoke(self(), input, { ...options, actor }) as Promise<InferOutput<TOutput>>,
     tool: () => toMcpTool(self()),
     openapi: () => toOpenApiOperation(self()),
-    client: (options) => clientMethodFor(actionName(self()), options),
+    client: (options) => clientMethodFor(actionName(self()), options, def.http?.path),
     job: () => toJobHandle(self()),
     contract: (options) => contractTestsFor(self(), options),
   };

package/src/http-path.ts

@@ -0,0 +1,131 @@
+/**
+ * Where an action is served: its pinned `http.path` when it declares one, else the app's
+ * `pathStyle` applied to its name. The style is declared ONCE per app (`defineApi({ http:
+ * { pathStyle } })`) and read lazily by every projection — the route, the OpenAPI operation, the
+ * descriptor, the deprecation successor — so no projection can hold a path the others do not.
+ */
+
+import type { ActionPathStyle, ActionRoute } from '@ultimat3/core';
+import { ACTION_PATH_STYLES, actionRoute } from '@ultimat3/core';
+import {
+  ActionHttpPathInvalidError,
+  ActionPathDerivedEarlyError,
+  ActionPathStyleInvalidError,
+} from './errors-http';
+import { defOf } from './invoke';
+import { seatedActions } from './registry-store';
+
+/**
+ * Name → the pin its registered action declares, read through the registry's leaf store, so a
+ * caller holding only a NAME (`derivePath`, a deprecation's `replacedBy`) gets the pinned URL.
+ */
+const pinOf = (name: string): string | undefined => {
+  const seated = seatedActions.get(name);
+  return seated === undefined ? undefined : defOf(seated).http?.path;
+};
+
+/** What an action may say about its own HTTP projection. */
+export interface ActionHttp {
+  /**
+   * Pin the URL, whatever the app's style derives — for a path a vendor was given and cannot be
+   * told to change (a webhook registered with a payment provider). Static and lowercase; the pin
+   * is also what a rename of the export can no longer move.
+   */
+  readonly path?: string;
+}
+
+/** Static, lowercase, no parameters, no trailing slash. */
+const PINNED_PATH = /^(\/[a-z0-9][a-z0-9._~-]*)+$/;
+
+let style: ActionPathStyle = 'resource';
+
+/**
+ * Every path handed out BY NAME (`derivePath`, `actionHttpPath('name')`), by name. A caller may
+ * keep the string — a page's form target in a module-level const — so a later style that moves
+ * one of these is a URL no route serves; `setActionPathStyle` refuses it instead. Bounded by the
+ * number of action names, and a path the new style keeps is not a stale one.
+ */
+const handedOut = new Map<string, string>();
+
+/** The app's declared style — `'resource'` until `defineApi` says otherwise. */
+export function actionPathStyle(): ActionPathStyle {
+  return style;
+}
+
+/** Called by `defineApi` (and the registry's re-derivation). Refuses an unknown style. */
+export function setActionPathStyle(next: unknown): ActionPathStyle {
+  if (!ACTION_PATH_STYLES.some((known) => known === next)) {
+    throw new ActionPathStyleInvalidError(next);
+  }
+  const declared = next as ActionPathStyle;
+  if (declared !== style) {
+    const stale = [...handedOut]
+      .map(([name, was]) => ({ name, was, now: routeUnder(declared, name, pinOf(name)).path }))
+      .filter((row) => row.now !== row.was)
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    if (stale.length > 0) throw new ActionPathDerivedEarlyError({ style: declared, stale });
+  }
+  style = declared;
+  return style;
+}
+
+/** Test seam, beside `resetRegistry`. */
+export function resetActionPathStyle(): void {
+  style = 'resource';
+  handedOut.clear();
+}
+
+/** Refuses a pin that is not a static lowercase path, or one under the framework's `/_x`. */
+export function assertPinnedPath(name: string, path: unknown): void {
+  if (typeof path !== 'string') {
+    throw new ActionHttpPathInvalidError({ name, path, reason: 'is not a string' });
+  }
+  if (!PINNED_PATH.test(path)) {
+    throw new ActionHttpPathInvalidError({
+      name,
+      path,
+      reason:
+        'is not a static lowercase path (a parameter, an uppercase letter or a trailing slash)',
+    });
+  }
+  if (path === '/_x' || path.startsWith('/_x/')) {
+    throw new ActionHttpPathInvalidError({
+      name,
+      path,
+      reason: 'claims /_x, the framework namespace',
+    });
+  }
+}
+
+/**
+ * The route for `name` under the current style, with `pin` replacing the path when present. The
+ * verb and resource stay the style's — they label the operation, the path is where it lives.
+ */
+export function routeFor(name: string, pin: string | undefined): ActionRoute {
+  return routeUnder(style, name, pin);
+}
+
+const routeUnder = (under: ActionPathStyle, name: string, pin: string | undefined): ActionRoute => {
+  const derived = actionRoute(name, under);
+  return pin === undefined ? derived : { ...derived, path: pin };
+};
+
+/**
+ * The route a registered NAME is served at, for the framework's own projections — the route
+ * table, the OpenAPI operation, a deprecation's successor. Re-derived on every call and never
+ * held by app code, so nothing is recorded: a test that mounted routes must not make a later
+ * test's style declaration look like a stranded capture.
+ */
+export function servedActionRoute(name: string): ActionRoute {
+  return routeFor(name, pinOf(name));
+}
+
+/**
+ * The same answer, handed to APP code by name (`derivePath`, `actionHttpPath('name')`) — which
+ * may keep the string, so it is the one recorded; see `handedOut`.
+ */
+export function resolveActionRoute(name: string): ActionRoute {
+  const route = servedActionRoute(name);
+  handedOut.set(name, route.path);
+  return route;
+}

package/src/http.ts

@@ -22,16 +22,16 @@ import type { ActionRateLimit, AnyAction } from './action';
 import type { Deprecation } from './deprecation';
 import { recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { ActionDeprecationInvalidError } from './errors';
+import { actionPathStyle, servedActionRoute } from './http-path';
 import { actionName, defOf, invoke } from './invoke';
 import {
-  derivePath,
   inputSchemaName,
   outputSchemaName,
   PROBLEM_SCHEMA_NAME,
   schemaRef,
   toOperationId,
 } from './naming';
-import { admitsAnonymous, policyCapability } from './policy-gate';
+import { admitsAnonymous, policyCapability, policyPermissions } from './policy-gate';
 import { carriesRecords, recordResponse } from './record-wire';
 import { IDEMPOTENCY_HEADER } from './wire-headers';
 
@@ -56,8 +56,30 @@ async function writeOriginOf(req: UltimateRequest): Promise<string | undefined>
  * kebab-cased (`updateUserProfile` -> `/api/user-profiles/update`). See `naming.ts`.
  */
 export function toRoute(target: AnyAction): Route {
+  return projectRoute(target, servedActionRoute(actionName(target)).path, (req) => req.bodyRaw());
+}
+
+/**
+ * The same action, bound to a PAGE's URL for `POST` (`defineRoute({ post: 'unsubscribe' })`): the
+ * URL's query members merged OVER the body's, so an RFC 8058 one-click `POST /baja?t=…` with
+ * `List-Unsubscribe=One-Click` reaches the action as `{ t, 'List-Unsubscribe': 'One-Click' }`.
+ * The query wins a name both carry — it is the URL the server minted. Everything else is
+ * `toRoute`'s: the policy, the idempotency, the redirect a handler asks for, the problem document.
+ */
+export function toPostBinding(target: AnyAction, path: string): Route {
+  return projectRoute(target, path, async (req) => {
+    const body = await req.bodyRaw();
+    const fields = typeof body === 'object' && body !== null && !Array.isArray(body) ? body : {};
+    return { ...fields, ...req.queryRaw() };
+  });
+}
+
+function projectRoute(
+  target: AnyAction,
+  path: string,
+  readInput: (req: UltimateRequest) => Promise<unknown>,
+): Route {
   const name = actionName(target);
-  const { path, resource } = derivePath(name);
   const def = defOf(target);
   // Rendered ONCE, at projection: a date that cannot become a header is a mount-time refusal,
   // not a surprise on the first request — the same rule `toBucket` follows for a rate limit.
@@ -80,7 +102,7 @@ export function toRoute(target: AnyAction): Route {
     //
     // The pipeline already parsed and size-capped the body; parsing it again here
     // would be a second, differently-behaved parser for the same bytes.
-    const raw = await req.bodyRaw();
+    const raw = await readInput(req);
     const key = def.idempotent === true ? req.header(IDEMPOTENCY_HEADER) : null;
     let replayed = false;
     // The header NAMES the write whatever the declaration, idempotent or not: a page sends one
@@ -138,7 +160,7 @@ export function toRoute(target: AnyAction): Route {
     // only ever added SCHEMA validation on top. `X_BODY_INVALID` keeps its job, which is a body
     // failing a plain `route.ts`'s own schema, where no primitive owns the input.
     cache: { mode: 'no-store', tags: tagKeys(def.cache?.invalidates ?? []) },
-    tags: [resource],
+    tags: [operationTagOf(target)],
     // Name AND numbers. The name alone selected a bucket the limiter's table never held, so
     // `bucketFor` fell through to `default` — 120 burst for an action that declared 5. The
     // numbers ride along and `withRouteBuckets` registers them at construction.
@@ -151,6 +173,22 @@ export function toRoute(target: AnyAction): Route {
   return { method: 'POST', path, handler, meta };
 }
 
+/**
+ * The operation's one tag. Under `'resource'` it is the derived resource, as it always was. Under
+ * `'readable'` the path no longer names a resource, and guessing one from the words after the verb
+ * is the defect the style exists to end (`signIn` → `in`) — so the tag is the resource the POLICY
+ * names (`can('cases:create')` → `cases`): whose operation it is, which is what a reader groups by.
+ */
+export function operationTagOf(target: AnyAction): string {
+  const name = actionName(target);
+  if (actionPathStyle() === 'resource') return servedActionRoute(name).resource;
+  const policy = defOf(target).policy;
+  // A grant first; an `allow('x:y')` names its resource in the label alone.
+  const named = policyPermissions(policy)[0] ?? policyCapability(policy);
+  const resource = /^([a-z0-9][a-z0-9_-]*):/i.exec(named)?.[1];
+  return resource === undefined ? 'api' : resource.toLowerCase();
+}
+
 export interface OpenApiOperation {
   readonly operationId: string;
   readonly tags: readonly string[];
@@ -168,14 +206,13 @@ export interface OpenApiOperation {
 export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
   const name = actionName(target);
   const def = defOf(target);
-  const path = derivePath(name);
   const idempotent = def.idempotent === true;
   const deprecation = deprecationMetaFor(name, def.deprecated);
   const outputRef = schemaRef(outputSchemaName(name));
   const enveloped = carriesRecords(target.output);
   return {
     operationId: toOperationId(name),
-    tags: [path.resource],
+    tags: [operationTagOf(target)],
     summary: def.mcp?.description ?? name,
     ...(deprecation === undefined ? {} : { deprecated: true }),
     parameters: idempotent ? [IDEMPOTENCY_PARAMETER] : [],
@@ -228,7 +265,7 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
 
 /**
  * The headers this action's `deprecated:` block renders to, or nothing. The successor's URL comes
- * from `derivePath` — the same derivation the route and the client use, never a second one.
+ * from `servedActionRoute` — `derivePath`'s derivation, the one the route and the client use.
  */
 function deprecationHeadersFor(
   name: string,
@@ -236,7 +273,7 @@ function deprecationHeadersFor(
 ): Readonly<Record<string, string>> | undefined {
   if (deprecated === undefined) return undefined;
   const successor =
-    deprecated.replacedBy === undefined ? undefined : derivePath(deprecated.replacedBy).path;
+    deprecated.replacedBy === undefined ? undefined : servedActionRoute(deprecated.replacedBy).path;
   const rendered = renderDeprecation(deprecated, successor);
   if (!rendered.ok) throw new ActionDeprecationInvalidError(name, rendered.field, rendered.value);
   return rendered.headers;

package/src/index.ts

@@ -57,6 +57,18 @@ export type {
   McpDescriptorMeta,
 } from './action';
 export { action, describeAction, isAction } from './action';
+/**
+ * The app's API as a whole — `defineApi({ http: { pathStyle, mounts }, openapi })` — read back by
+ * the boot (bearer mounts) and `x manifest` (the complete and per-mount documents).
+ */
+export type {
+  ApiDeclaration,
+  ApiHttp,
+  ApiMount,
+  ApiOpenApi,
+  OpenApiServer,
+} from './api-declaration';
+export { apiDeclaration } from './api-declaration';
 /**
  * The audit seam. `AuditSink` is the whole extension point: the framework supplies the record
  * and never the row. `audit-gate.ts` stays unexported — the sink has one caller, and that
@@ -123,14 +135,24 @@ export {
   RemoteActionError,
   RpcFailedError,
 } from './errors';
+export {
+  ActionHttpPathInvalidError,
+  ActionPathStyleInvalidError,
+  OpenApiConfigInvalidError,
+} from './errors-http';
 export type { OpenApiOperation } from './http';
 export {
   BUILD_ID_HEADER,
   IDEMPOTENCY_HEADER,
+  operationTagOf,
   REPLAYED_HEADER,
   toOpenApiOperation,
+  toPostBinding,
   toRoute,
 } from './http';
+/** `http: { path }` on an action pins its URL; the app's `pathStyle` derives every other one. */
+export type { ActionHttp } from './http-path';
+export { actionPathStyle } from './http-path';
 /**
  * The idempotency seam. `withIdempotency` and `IDEMPOTENCY_HEADER` are both public, so a plain
  * mutating `route` can reserve-and-replay exactly as an action does — `idempotencyKeyFor` is the
@@ -208,6 +230,12 @@ export type { ActionPath } from './naming';
 export { derivePath, inputSchemaName, outputSchemaName, pluralize } from './naming';
 export type { BuildOpenApiOptions, OpenApiDocument, OpenApiInfo } from './openapi';
 export { buildOpenApi, serializeOpenApi } from './openapi';
+export {
+  BEARER_SCHEME,
+  COOKIE_SCHEME,
+  completeOpenApi,
+  mountOpenApi,
+} from './openapi-complete';
 export type { ActionPolicy, PolicySubject, Surface } from './policy-gate';
 /**
  * `policyCapability` is the display label; `policyPermissions` is what a report MATCHES on.
@@ -223,6 +251,8 @@ export {
   policyPermissions,
 } from './policy-gate';
 export {
+  actionHttpPath,
+  configureActionPathStyle,
   describeActions,
   getAction,
   listActions,

package/src/mutator.ts

@@ -18,6 +18,7 @@ import type {
 } from './action';
 import { action, isAction } from './action';
 import type { Deprecation } from './deprecation';
+import type { ActionHttp } from './http-path';
 import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
 
@@ -94,6 +95,8 @@ export interface MutatorDef<
   readonly rateLimit?: ActionRateLimit;
   /** Same key, same meaning as an action's: `Deprecation`/`Sunset` on every response. */
   readonly deprecated?: Deprecation;
+  /** Same key, same meaning as an action's: `http: { path }` pins the URL. */
+  readonly http?: ActionHttp;
   readonly idempotent?: boolean;
   /**
    * The row a row-level `policy` decides about — an action's `row`, and dropped on the way into
@@ -164,6 +167,7 @@ export function mutator<
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
+    ...(def.http === undefined ? {} : { http: def.http }),
     ...(row === undefined ? {} : { row: (args: ActionRowArgs<TInput>) => row.call(def, args) }),
     ...(def.idempotent === undefined ? {} : { idempotent: def.idempotent }),
     ...(def.audit === undefined ? {} : { audit: def.audit }),

package/src/naming.ts

@@ -6,7 +6,8 @@
  */
 
 import type { ActionRoute } from '@ultimat3/core';
-import { actionRoute, splitWords } from '@ultimat3/core';
+import { splitWords } from '@ultimat3/core';
+import { resolveActionRoute } from './http-path';
 
 /**
  * The path rule is `@ultimat3/core`'s `client-paths.ts` — the typed client, the route and the
@@ -18,12 +19,15 @@ export { pluralize, splitWords } from '@ultimat3/core';
 export type ActionPath = ActionRoute;
 
 /**
- * `publishPost`        -> POST /api/posts/publish
- * `updateUserProfile`  -> POST /api/user-profiles/update
- * `checkout`           -> POST /api/checkouts/invoke   (single-word fallback)
+ * Where the action NAMED `name` is served, as the running app serves it: its `http.path` pin
+ * when the registered action declares one, else the app's `pathStyle` over the name.
+ *
+ * `'resource'` (the default): `publishPost` -> POST /api/posts/publish,
+ * `updateUserProfile` -> /api/user-profiles/update, `checkout` -> /api/checkouts/invoke.
+ * `'readable'`: `publishPost` -> /api/publish-post, `signIn` -> /api/sign-in.
  */
 export function derivePath(name: string): ActionPath {
-  return actionRoute(name);
+  return resolveActionRoute(name);
 }
 
 // There is deliberately no `toToolName`. An MCP tool name is the export name verbatim — the one

package/src/openapi-complete.ts

@@ -0,0 +1,287 @@
+/**
+ * The COMPLETE document an app opts into with `defineApi({ openapi })`: its own `info` and
+ * `servers`, the security schemes its routes are reached through, and the two refusals every
+ * authenticated operation can answer — 401 and 429, with `Retry-After` — which the per-primitive
+ * projections cannot state because they do not know the route an operation is mounted as. Plus
+ * the second document a bearer mount publishes: only the cut, at the mounted paths.
+ *
+ * Built over the merged document (actions AND reads — `@ultimat3/cli` merges the two packages'
+ * paths) and over the `Route`s that serve it, so "is this operation authenticated" is the answer
+ * `meta.auth` gives the pipeline, never a second derivation. Deterministic like `openapi.ts`: the
+ * inputs are sorted and nothing reads the clock or the environment.
+ */
+
+import type { Route } from '@ultimat3/http';
+import { mountedPath } from '@ultimat3/http';
+import type { ApiMount, ApiOpenApi } from './api-declaration';
+import type { JsonSchemaObject } from './json-schema';
+import { PROBLEM_SCHEMA_NAME, schemaRef } from './naming';
+import type { OpenApiDocument } from './openapi';
+
+/** `components.securitySchemes` keys. */
+export const COOKIE_SCHEME = 'cookie';
+export const BEARER_SCHEME = 'bearer';
+
+type Operation = Record<string, unknown>;
+
+const BEARER_SECURITY_SCHEME = {
+  type: 'http',
+  scheme: 'bearer',
+  description: 'A token issued by the app, sent as Authorization: Bearer <token>.',
+};
+
+const RATE_LIMIT_HEADERS: Record<string, unknown> = {
+  'RateLimit-Limit': {
+    description: 'Requests the bucket admits per window.',
+    schema: { type: 'integer' },
+  },
+  'RateLimit-Remaining': {
+    description: 'Requests left in the current window.',
+    schema: { type: 'integer' },
+  },
+  'RateLimit-Reset': {
+    description: 'Seconds until the bucket is full again.',
+    schema: { type: 'integer' },
+  },
+};
+
+const RETRY_AFTER_HEADER: Record<string, unknown> = {
+  'Retry-After': {
+    description: 'Seconds to wait before retrying.',
+    schema: { type: 'integer', minimum: 1 },
+  },
+};
+
+function problem(description: string, headers?: Record<string, unknown>): Record<string, unknown> {
+  return {
+    description,
+    ...(headers === undefined ? {} : { headers }),
+    content: { 'application/problem+json': { schema: { $ref: schemaRef(PROBLEM_SCHEMA_NAME) } } },
+  };
+}
+
+const lower = (method: string): string => method.toLowerCase();
+
+/** `method path` → the route that serves it. */
+function routeIndex(routes: readonly Route[]): ReadonlyMap<string, Route> {
+  return new Map(routes.map((route) => [`${lower(route.method)} ${route.path}`, route]));
+}
+
+interface Refusals {
+  readonly scheme: string;
+  /** The mount's own allowance applies to every operation, whatever the route declares. */
+  readonly everyOpLimited: boolean;
+  readonly unauthorizedHeaders?: Record<string, unknown>;
+}
+
+/** One operation, with its route's refusals and security added. Never mutates `operation`. */
+function completeOperation(operation: Operation, route: Route | undefined, refusals: Refusals) {
+  const authenticated = route?.meta.auth === 'required';
+  const limited = refusals.everyOpLimited || route?.meta.rateLimitBucket !== undefined;
+  if (!authenticated && !limited) return operation;
+  const responses = { ...(operation['responses'] as Record<string, unknown>) };
+  if (limited) {
+    const ok = responses['200'] as Record<string, unknown> | undefined;
+    if (ok !== undefined) {
+      responses['200'] = {
+        ...ok,
+        headers: {
+          ...(ok['headers'] as Record<string, unknown> | undefined),
+          ...RATE_LIMIT_HEADERS,
+        },
+      };
+    }
+  }
+  if (authenticated) {
+    responses['401'] = problem(
+      'X_UNAUTHENTICATED — no credential, or one that did not resolve',
+      refusals.unauthorizedHeaders,
+    );
+  }
+  responses['429'] = problem(
+    'X_RATE_LIMITED — retry after Retry-After seconds',
+    limited ? { ...RETRY_AFTER_HEADER, ...RATE_LIMIT_HEADERS } : RETRY_AFTER_HEADER,
+  );
+  return {
+    ...operation,
+    responses,
+    ...(authenticated ? { security: [{ [refusals.scheme]: [] }] } : {}),
+  };
+}
+
+function mapOperations(
+  paths: Record<string, unknown>,
+  visit: (path: string, method: string, operation: Operation) => Operation,
+): Record<string, unknown> {
+  // `fromEntries`, never `out[path] = …`: a path is a key, and assigning `__proto__` runs a setter.
+  return Object.fromEntries(
+    Object.entries(paths).map(([path, item]) => [
+      path,
+      Object.fromEntries(
+        Object.entries(item as Record<string, Operation>).map(([method, operation]) => [
+          method,
+          visit(path, method, operation),
+        ]),
+      ),
+    ]),
+  );
+}
+
+function infoOf(document: OpenApiDocument, declared: ApiOpenApi) {
+  return {
+    title: declared.title ?? document.info.title,
+    version: declared.version ?? document.info.version,
+    ...(declared.description === undefined ? {} : { description: declared.description }),
+  };
+}
+
+const serversOf = (declared: ApiOpenApi) =>
+  declared.servers === undefined || declared.servers.length === 0
+    ? {}
+    : {
+        servers: declared.servers.map((server) => ({
+          url: server.url,
+          ...(server.description === undefined ? {} : { description: server.description }),
+        })),
+      };
+
+/**
+ * `openapi.json`, complete: the app's `info` and `servers`, a `cookie` security scheme (plus
+ * `bearer` when a mount exists — it is the same API reached another way), and 401/429 on every
+ * operation its route authenticates.
+ */
+export function completeOpenApi(
+  document: OpenApiDocument,
+  input: {
+    readonly declared: ApiOpenApi;
+    readonly routes: readonly Route[];
+    readonly bearer: boolean;
+  },
+): OpenApiDocument {
+  const index = routeIndex(input.routes);
+  const paths = mapOperations(document.paths, (path, method, operation) =>
+    completeOperation(operation, index.get(`${method} ${path}`), {
+      scheme: COOKIE_SCHEME,
+      everyOpLimited: false,
+    }),
+  );
+  return {
+    ...document,
+    info: infoOf(document, input.declared),
+    ...serversOf(input.declared),
+    paths,
+    components: {
+      ...document.components,
+      securitySchemes: {
+        [COOKIE_SCHEME]: {
+          type: 'apiKey',
+          in: 'cookie',
+          name: input.declared.sessionCookie ?? 'session',
+        },
+        ...(input.bearer ? { [BEARER_SCHEME]: BEARER_SECURITY_SCHEME } : {}),
+      },
+    },
+  };
+}
+
+/**
+ * A bearer mount's own document: only the operations its `scopes` name, re-keyed to the mounted
+ * paths, each `bearer`-secured with 401, 404-when-hidden and 429, and only the schemas those
+ * operations reference. `x-ultimate.scope` names the scope a token needs for each.
+ */
+export function mountOpenApi(
+  document: OpenApiDocument,
+  input: {
+    readonly declared: ApiOpenApi;
+    readonly mount: ApiMount;
+    readonly routes: readonly Route[];
+  },
+): OpenApiDocument {
+  const { mount } = input;
+  const scopeOf = new Map<string, string>();
+  for (const [scope, names] of Object.entries(mount.scopes)) {
+    for (const name of names) scopeOf.set(name, scope);
+  }
+  // A `Map`: the key is a route path, and a plain object keyed by one would read `__proto__`.
+  const mountedItems = new Map<string, Record<string, unknown>>();
+  const tags = new Set<string>();
+  const byRoute = [...input.routes].sort((a, b) =>
+    `${a.path} ${a.method}` < `${b.path} ${b.method}` ? -1 : 1,
+  );
+  for (const route of byRoute) {
+    const scope = scopeOf.get(route.meta.name);
+    if (scope === undefined) continue;
+    const method = lower(route.method);
+    const item = (
+      Object.hasOwn(document.paths, route.path) ? document.paths[route.path] : undefined
+    ) as Record<string, Operation> | undefined;
+    const operation = item?.[method];
+    if (operation === undefined) continue;
+    const completed = completeOperation(
+      operation,
+      { ...route, meta: { ...route.meta, auth: 'required' } },
+      {
+        scheme: BEARER_SCHEME,
+        everyOpLimited: mount.rateLimit !== undefined,
+        unauthorizedHeaders: {
+          'WWW-Authenticate': { description: 'Bearer', schema: { type: 'string' } },
+        },
+      },
+    );
+    const responses = {
+      ...(completed['responses'] as Record<string, unknown>),
+      '404': problem('X_ROUTE_NOT_FOUND — also the answer for a token without this scope'),
+    };
+    const extensions = (completed['x-ultimate'] as Record<string, unknown> | undefined) ?? {};
+    for (const tag of (completed['tags'] as readonly string[] | undefined) ?? []) tags.add(tag);
+    const mounted = mountedPath(mount.prefix, route.path);
+    mountedItems.set(mounted, {
+      ...mountedItems.get(mounted),
+      [method]: { ...completed, responses, 'x-ultimate': { ...extensions, scope } },
+    });
+  }
+  const paths = Object.fromEntries(mountedItems);
+  const schemas = referencedSchemas(paths, document.components.schemas);
+  return {
+    openapi: document.openapi,
+    info: infoOf(document, input.declared),
+    ...serversOf(input.declared),
+    paths,
+    components: {
+      schemas,
+      securitySchemes: { [BEARER_SCHEME]: BEARER_SECURITY_SCHEME },
+    },
+    tags: [...tags].sort().map((name) => ({ name })),
+  };
+}
+
+/** Every component schema `root` reaches through `$ref`, transitively. */
+function referencedSchemas(
+  root: unknown,
+  schemas: Readonly<Record<string, JsonSchemaObject>>,
+): Record<string, JsonSchemaObject> {
+  const prefix = '#/components/schemas/';
+  const found: Record<string, JsonSchemaObject> = {};
+  const pending: unknown[] = [root];
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (Array.isArray(node)) {
+      pending.push(...node);
+      continue;
+    }
+    if (typeof node !== 'object' || node === null) continue;
+    for (const [key, value] of Object.entries(node)) {
+      if (key === '$ref' && typeof value === 'string' && value.startsWith(prefix)) {
+        const name = value.slice(prefix.length);
+        const schema = Object.hasOwn(schemas, name) ? schemas[name] : undefined;
+        if (schema !== undefined && !Object.hasOwn(found, name)) {
+          found[name] = schema;
+          pending.push(schema);
+        }
+      } else {
+        pending.push(value);
+      }
+    }
+  }
+  return found;
+}

package/src/openapi.ts

@@ -8,23 +8,31 @@
  */
 
 import type { AnyAction } from './action';
-import { toOpenApiOperation } from './http';
+import { operationTagOf, toOpenApiOperation } from './http';
+import { servedActionRoute } from './http-path';
 import { actionName } from './invoke';
 import { type JsonSchemaObject, jsonSchemaOf, sortSchema } from './json-schema';
-import { derivePath, inputSchemaName, outputSchemaName, PROBLEM_SCHEMA_NAME } from './naming';
+import { inputSchemaName, outputSchemaName, PROBLEM_SCHEMA_NAME } from './naming';
 import { listActions } from './registry';
 import { stableStringify } from './stable';
 
 export interface OpenApiInfo {
   readonly title: string;
   readonly version: string;
+  readonly description?: string;
 }
 
 export interface OpenApiDocument {
   readonly openapi: '3.1.0';
   readonly info: OpenApiInfo;
+  /** Only in the complete document (`defineApi({ openapi: { servers } })`). */
+  readonly servers?: readonly { readonly url: string; readonly description?: string }[];
   readonly paths: Record<string, unknown>;
-  readonly components: { readonly schemas: Record<string, JsonSchemaObject> };
+  readonly components: {
+    readonly schemas: Record<string, JsonSchemaObject>;
+    /** Only in the complete document — `completeOpenApi` / `mountOpenApi`. */
+    readonly securitySchemes?: Readonly<Record<string, unknown>>;
+  };
   readonly tags: readonly { readonly name: string }[];
 }
 
@@ -43,11 +51,11 @@ export function buildOpenApi(options: BuildOpenApiOptions = {}): OpenApiDocument
 
   for (const target of actions) {
     const name = actionName(target);
-    const { path, resource } = derivePath(name);
+    const { path } = servedActionRoute(name);
     paths[path] = { post: toOpenApiOperation(target) };
     schemas[inputSchemaName(name)] = sortSchema(jsonSchemaOf(target.input));
     schemas[outputSchemaName(name)] = sortSchema(jsonSchemaOf(target.output));
-    tags.add(resource);
+    tags.add(operationTagOf(target));
   }
 
   return {

package/src/registry-store.ts

@@ -0,0 +1,9 @@
+/**
+ * The registered actions, by name — the one map, held in a leaf so `http-path.ts` can resolve a
+ * NAME to its declaration (a pinned `http.path`) without importing `registry.ts`, which imports
+ * `action.ts`, which imports `http-path.ts`. `registry.ts` is the only writer.
+ */
+
+import type { AnyAction } from './action';
+
+export const seatedActions = new Map<string, AnyAction>();

package/src/registry.ts

@@ -4,15 +4,26 @@
  * actions. Registration is also where a missing policy becomes a build error.
  */
 
+import type { ActionPathStyle } from '@ultimat3/core';
 import { SchemaUnsupportedError } from '@ultimat3/schema';
 import type { ActionDescriptor, AnyAction } from './action';
 import { isAction, nameAction } from './action';
+import { resetApiDeclaration } from './api-declaration';
 import { ActionDuplicateError, ActionPathDuplicateError, ActionPolicyMissingError } from './errors';
+import {
+  assertPinnedPath,
+  resetActionPathStyle,
+  resolveActionRoute,
+  routeFor,
+  setActionPathStyle,
+} from './http-path';
 import { assertIdempotencyScope } from './idempotency';
+import { defOf } from './invoke';
 import { jsonSchemaOf, mcpSchemaOf } from './json-schema';
-import { derivePath } from './naming';
+import type { ActionPath } from './naming';
+import { seatedActions } from './registry-store';
 
-const registry = new Map<string, AnyAction>();
+const registry = seatedActions;
 
 /**
  * Derived route -> the action name that owns it. A second index because the name is not the
@@ -46,7 +57,9 @@ export function registerAction<A extends AnyAction>(name: string, target: A): A
     throw new ActionPolicyMissingError(name);
   }
   assertProjectable(name, target);
-  const { path } = derivePath(name);
+  const pin = defOf(target).http?.path;
+  if (pin !== undefined) assertPinnedPath(name, pin);
+  const { path } = routeFor(name, pin);
   const owner = paths.get(path);
   if (owner !== undefined && owner !== name) {
     throw new ActionPathDuplicateError({ name, existing: owner, path });
@@ -57,6 +70,35 @@ export function registerAction<A extends AnyAction>(name: string, target: A): A
   return named;
 }
 
+/**
+ * Where `target` is served — its pin, else the app's style over its name. A NAME is resolved
+ * through the registry, so a pin declared on the action is honoured for a caller that only has the
+ * name (a deprecation's `replacedBy`, a page minting an island's endpoint).
+ */
+export function actionHttpPath(target: AnyAction | string): ActionPath {
+  // By NAME is how a page mints a form target, so it answers through the recorded path.
+  if (typeof target === 'string') return resolveActionRoute(target);
+  return routeFor(target.name, defOf(target).http?.path);
+}
+
+/**
+ * The app's `pathStyle`, applied to every action already seated and every one registered after.
+ * Re-derived whole, so two names the new style folds onto one URL are refused here rather than
+ * left for the router to seat one of.
+ */
+export function configureActionPathStyle(style: ActionPathStyle): void {
+  setActionPathStyle(style);
+  paths.clear();
+  for (const [name, target] of [...registry.entries()].sort(byName)) {
+    const { path } = routeFor(name, defOf(target).http?.path);
+    const owner = paths.get(path);
+    if (owner !== undefined && owner !== name) {
+      throw new ActionPathDuplicateError({ name, existing: owner, path });
+    }
+    paths.set(path, name);
+  }
+}
+
 /**
  * Both schemas must reach JSON Schema, and this is where that is decided — boot, beside the policy
  * check, never the first `tools/list`. `jsonSchemaOf` used to swallow the refusal into
@@ -114,6 +156,8 @@ export function describeActions(): readonly ActionDescriptor[] {
 export function resetRegistry(): void {
   registry.clear();
   paths.clear();
+  resetActionPathStyle();
+  resetApiDeclaration();
 }
 
 function byName(a: readonly [string, AnyAction], b: readonly [string, AnyAction]): number {