@ultimat3/action 22.6.0 → 22.6.1

package/README.md

@@ -185,6 +185,12 @@ One rule per app, declared once — `defineApi({ http: { pathStyle } })` — plu
   `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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.6.0",
+  "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.6.0",
-    "@ultimat3/core": "22.6.0",
-    "@ultimat3/entity": "22.6.0",
-    "@ultimat3/http": "22.6.0",
-    "@ultimat3/policy": "22.6.0",
-    "@ultimat3/schema": "22.6.0"
+    "@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/errors-http.ts

@@ -27,6 +27,35 @@ export class ActionPathStyleInvalidError extends UltimateError {
   }
 }
 
+/**
+ * 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({

package/src/errors.ts

@@ -58,6 +58,7 @@ const OWNED_TITLES: Readonly<Record<string, string>> = {
   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/http-path.ts

@@ -7,7 +7,11 @@
 
 import type { ActionPathStyle, ActionRoute } from '@ultimat3/core';
 import { ACTION_PATH_STYLES, actionRoute } from '@ultimat3/core';
-import { ActionHttpPathInvalidError, ActionPathStyleInvalidError } from './errors-http';
+import {
+  ActionHttpPathInvalidError,
+  ActionPathDerivedEarlyError,
+  ActionPathStyleInvalidError,
+} from './errors-http';
 import { defOf } from './invoke';
 import { seatedActions } from './registry-store';
 
@@ -35,6 +39,14 @@ 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;
@@ -45,13 +57,22 @@ export function setActionPathStyle(next: unknown): ActionPathStyle {
   if (!ACTION_PATH_STYLES.some((known) => known === next)) {
     throw new ActionPathStyleInvalidError(next);
   }
-  style = next as ActionPathStyle;
+  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`. */
@@ -81,11 +102,30 @@ export function assertPinnedPath(name: string, path: unknown): void {
  * 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 {
-  const derived = actionRoute(name, style);
+  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 route a registered NAME is served at: its pin when it declares one, else the style's. */
+/**
+ * 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 {
-  return routeFor(name, pinOf(name));
+  const route = servedActionRoute(name);
+  handedOut.set(name, route.path);
+  return route;
 }

package/src/http.ts

@@ -22,10 +22,9 @@ import type { ActionRateLimit, AnyAction } from './action';
 import type { Deprecation } from './deprecation';
 import { recordDeprecatedCall, renderDeprecation } from './deprecation';
 import { ActionDeprecationInvalidError } from './errors';
-import { actionPathStyle } from './http-path';
+import { actionPathStyle, servedActionRoute } from './http-path';
 import { actionName, defOf, invoke } from './invoke';
 import {
-  derivePath,
   inputSchemaName,
   outputSchemaName,
   PROBLEM_SCHEMA_NAME,
@@ -57,7 +56,7 @@ 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, derivePath(actionName(target)).path, (req) => req.bodyRaw());
+  return projectRoute(target, servedActionRoute(actionName(target)).path, (req) => req.bodyRaw());
 }
 
 /**
@@ -182,7 +181,7 @@ function projectRoute(
  */
 export function operationTagOf(target: AnyAction): string {
   const name = actionName(target);
-  if (actionPathStyle() === 'resource') return derivePath(name).resource;
+  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);
@@ -266,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,
@@ -274,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/openapi.ts

@@ -9,9 +9,10 @@
 
 import type { AnyAction } from './action';
 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';
 
@@ -50,7 +51,7 @@ export function buildOpenApi(options: BuildOpenApiOptions = {}): OpenApiDocument
 
   for (const target of actions) {
     const name = actionName(target);
-    const { path } = 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));

package/src/registry.ts

@@ -10,7 +10,13 @@ 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, routeFor, setActionPathStyle } from './http-path';
+import {
+  assertPinnedPath,
+  resetActionPathStyle,
+  resolveActionRoute,
+  routeFor,
+  setActionPathStyle,
+} from './http-path';
 import { assertIdempotencyScope } from './idempotency';
 import { defOf } from './invoke';
 import { jsonSchemaOf, mcpSchemaOf } from './json-schema';
@@ -70,10 +76,8 @@ export function registerAction<A extends AnyAction>(name: string, target: A): A
  * name (a deprecation's `replacedBy`, a page minting an island's endpoint).
  */
 export function actionHttpPath(target: AnyAction | string): ActionPath {
-  if (typeof target === 'string') {
-    const seated = registry.get(target);
-    return seated === undefined ? routeFor(target, undefined) : actionHttpPath(seated);
-  }
+  // 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);
 }
 
@@ -86,7 +90,7 @@ export function configureActionPathStyle(style: ActionPathStyle): void {
   setActionPathStyle(style);
   paths.clear();
   for (const [name, target] of [...registry.entries()].sort(byName)) {
-    const { path } = actionHttpPath(target);
+    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 });