@ultimat3/action 23.0.0 → 25.0.0

package/src/error-titles.ts

@@ -0,0 +1,51 @@
+// @ultimat3/action's error TITLES, registered at import — the one module `sideEffects` names, so
+// `errors.ts` (the classes) is unlisted and a chunk carries it only where it constructs a class:
+// Bun >= 1.4.1 honours the array and keeps a listed module wherever the barrel reaches it.
+// `index.ts` imports this bare, because `problemError` rebuilds a server's refusal by code and reads
+// its title from the registry; `errors.ts` and its two siblings import it bare as well.
+
+import { registerErrorCodes } from '@ultimat3/core';
+
+/**
+ * Titles for the framework-wide code table — every one of them owned by this package.
+ * `X_INPUT_INVALID` and `X_RPC_FAILED` are action's: an action is where an input schema is
+ * enforced and where the typed client speaks, and `@ultimat3/query` only throws them.
+ * Authz codes are absent on purpose — `ActionDeniedError` re-uses the policy decision's code.
+ */
+export const ACTION_ERROR_TITLES: Readonly<Record<string, string>> = {
+  X_ACTION_DUPLICATE: 'two actions are registered under one name',
+  X_AUDIT_SINK_FAILED: 'an audited action ran and the audit sink refused its record',
+  X_AUDIT_SINK_MISSING: 'an action declares audit: true and no audit sink is installed',
+  X_ACTION_DEPRECATION_INVALID: 'an action declares a deprecation whose dates cannot be rendered',
+  X_ACTION_PATH_DUPLICATE: 'two actions derive one HTTP path',
+  X_ACTION_FOREIGN: 'a value that is not an action was projected as one',
+  X_ACTION_POLICY_MISSING: 'an action was registered without a policy',
+  X_ACTION_UNREGISTERED: 'an action was projected before it was registered',
+  X_CONTRACT_DRIFT: 'client and server disagree about the contract',
+  X_IDEMPOTENCY_CONFLICT: 'idempotency key reused with a different payload or still in flight',
+  X_IDEMPOTENCY_KEY_INVALID: 'an Idempotency-Key was sent that cannot identify one request',
+  X_IDEMPOTENCY_NOT_SHARED:
+    'idempotency is declared fleet-wide and the installed store is per-process',
+  X_IDEMPOTENCY_REPLAYED_FAILURE:
+    'a retried Idempotency-Key replays a first attempt that failed after it may have committed',
+  X_IDEMPOTENCY_STATUS_UNKNOWN: 'an idempotency record holds a status this build cannot read',
+  X_INPUT_INVALID: 'input failed schema validation',
+  X_MUTATOR_CLOCK_MISSING:
+    "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',
+  X_MUTATOR_NOT_IDEMPOTENT: 'a mutator is declared without idempotent: true',
+  X_IDEMPOTENCY_RESERVATION_LOST:
+    "an idempotent action's reservation was taken over before its transaction could settle it",
+  X_IDEMPOTENT_REPLAY_REDACTED: 'an idempotent replay would return a field redacted at rest',
+};
+
+// One unconditional call: a presence guard would turn "another package claims one of these codes"
+// from an X_ERROR_CODE_DUPLICATE at import into whichever module loaded first deciding the title.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(ACTION_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);

package/src/errors-http.ts

@@ -1,10 +1,12 @@
 /**
  * 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.
+ * titles are registered in `error-titles.ts`, one registry, imported bare so constructing one of
+ * these registers its title first.
  */
 
 import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import './error-titles';
 
 export class ActionHttpPathInvalidError extends UltimateError {
   constructor(input: { name: string; path: unknown; reason: string }) {

package/src/errors-idempotency.ts

@@ -1,10 +1,11 @@
 /**
- * The five idempotency failures, split out of `errors.ts` at its line ceiling. One subclass per
- * stable code, exactly as there — the codes and their titles stay in `errors.ts`'s one
+ * The idempotency failures, split out of `errors.ts` at its line ceiling. One subclass per
+ * stable code, exactly as there — the codes and their titles stay in `error-titles.ts`'s one
  * `registerErrorCodes` call, because a second registration is how two modules end up deciding a
- * title by load order.
+ * title by load order. Imported bare, so constructing one of these registers its title first.
  */
 import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import './error-titles';
 // Type-only: `idempotency.ts` imports the classes below, and a runtime edge here would close the
 // cycle. `verbatimModuleSyntax` is what makes that guarantee mechanical.
 import type { IdempotencyFailure } from './idempotency';
@@ -77,14 +78,14 @@ export class IdempotencyNotSharedError extends UltimateError {
       // positional form is `unsafe`), so that line compiled and would have thrown on the first
       // reservation. The framework's own boot already installs this store; a host booting the
       // framework itself wraps the client it opened.
-      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) } })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
+      fix: "the framework boot installs a shared store — reach this only from a host that boots it itself: setIdempotencyStore(postgresIdempotencyStore({ executor: { query: (text, values) => client.query({ text, values }) }, origin: () => client, reclaimAfterMs: requestDeadlineMs })) from '@ultimat3/action', or drop the declaration to configureIdempotency({ scope: 'process' })",
       meta: { storeScope: storeScope ?? null },
     });
   }
 }
 
 /**
- * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guard()`
+ * The replay of a first attempt that FAILED. It is a replay and not a re-run on purpose: `guardAction()`
  * and the input parse both run before the idempotency gate, so everything the gate can see throw
  * is post-authorization and possibly post-commit — a handler that took the money and then failed
  * its own `output:` schema is the case this exists for. Releasing the reservation there let the
@@ -138,3 +139,54 @@ export class IdempotencyStatusUnknownError extends UltimateError {
     });
   }
 }
+
+/**
+ * A mutator declared without `idempotent: true`. Refused at declaration: the client replays a
+ * mutator's write under one `Idempotency-Key` (a retry, an offline queue draining after a lost
+ * response), and `toRoute` reads that key only for an idempotent action — so the alternative is a
+ * toggle that flips back, with nothing in any log to say the handler ran twice.
+ */
+export class MutatorNotIdempotentError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_MUTATOR_NOT_IDEMPOTENT',
+      cause:
+        'a mutator is declared without idempotent: true, so a replay of its write under the same Idempotency-Key would run the server half a second time',
+      fix: 'add `idempotent: true` to the mutator definition',
+    });
+  }
+}
+
+/**
+ * A settlement inside the handler's transaction matched no record: the attempt ran past the
+ * request deadline, a retry reclaimed the key, and this one no longer owns it. THROWN, where the
+ * autocommit path only logs — nothing here has committed, so the throw rolls this attempt's
+ * writes back and the retry's are the only ones stored.
+ */
+export class IdempotencyReservationLostError extends UltimateError {
+  constructor(key: string) {
+    super({
+      code: 'X_IDEMPOTENCY_RESERVATION_LOST',
+      cause: `idempotency key "${key}" was reclaimed by a retry while this attempt was still in flight past the request deadline, so its transaction is rolled back rather than committed beside the retry's`,
+      fix: 'resend this request with the same Idempotency-Key — the attempt that took the key over answers it, and this one was rolled back',
+      meta: { key },
+    });
+  }
+}
+
+/**
+ * A replay of a settled answer that had a field redacted at rest. Refused, never served: the
+ * stored copy holds `[redacted]` where the first caller got a credential, and handing that back
+ * as "the answer" is a silent wrong value. The first attempt RAN — a fresh key runs it again, so
+ * the fix names reading its effect as the way to recover the result.
+ */
+export class IdempotentReplayRedactedError extends UltimateError {
+  constructor(key: string) {
+    super({
+      code: 'X_IDEMPOTENT_REPLAY_REDACTED',
+      cause: `the answer stored for idempotency key "${key}" had a secret-named field redacted when it settled, so it cannot be replayed faithfully`,
+      fix: "x actions describe '<action>' --json   # the call already ran and showed its secret once — read its effect with a query; a new Idempotency-Key runs it again (a second credential)",
+      meta: { key, replayed: true },
+    });
+  }
+}

package/src/errors.ts

@@ -1,7 +1,7 @@
 /**
  * Every failure @ultimat3/action can produce, one subclass per stable code so
  * callers `instanceof` a specific failure instead of string-matching a message.
- * The idempotency five live in `errors-idempotency.ts` — this file reached the line ceiling —
+ * The idempotency failures live in `errors-idempotency.ts` — this file reached the line ceiling —
  * and are re-exported here, so `./errors` stays the one import path for all of them.
  */
 import {
@@ -9,15 +9,20 @@ import {
   deniedCallerFix,
   ERROR_DOCS_URL,
   hasErrorCode,
-  registerErrorCodes,
   renderFixShellArg,
   retryForStatus,
   UltimateError,
+  withStatedDelay,
 } from '@ultimat3/core';
 import type { SurfaceDenial } from '@ultimat3/policy';
 import type { ValidationIssue } from '@ultimat3/schema';
+// The titles are `error-titles.ts`, imported bare: this module is then side-effect-free and the
+// array does not list it, so a chunk keeps only the classes it constructs, and a chunk that
+// constructs one still registers every title first — anchored by use. The barrel imports it bare
+// too, for the browser that rebuilds a SERVER's refusal by code and constructs nothing from here.
+import './error-titles';
 
-// Re-exported, not re-declared: the five idempotency failures moved to their own file when this
+// Re-exported, not re-declared: the idempotency failures moved to their own file when this
 // one reached the line ceiling, and every importer still reads them from `./errors`.
 export type { IdempotencyConflictReason, IdempotencyKeyProblem } from './errors-idempotency';
 export {
@@ -25,49 +30,12 @@ export {
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
   IdempotencyReplayedFailureError,
+  IdempotencyReservationLostError,
   IdempotencyStatusUnknownError,
+  IdempotentReplayRedactedError,
+  MutatorNotIdempotentError,
 } from './errors-idempotency';
 
-/**
- * Titles for the framework-wide code table — every one of them owned by this package.
- * `X_INPUT_INVALID` and `X_RPC_FAILED` are action's: an action is where an input schema is
- * enforced and where the typed client speaks, and `@ultimat3/query` only throws them.
- * Authz codes are absent on purpose — `ActionDeniedError` re-uses the policy decision's code.
- */
-const OWNED_TITLES: Readonly<Record<string, string>> = {
-  X_ACTION_DUPLICATE: 'two actions are registered under one name',
-  X_AUDIT_SINK_FAILED: 'an audited action ran and the audit sink refused its record',
-  X_AUDIT_SINK_MISSING: 'an action declares audit: true and no audit sink is installed',
-  X_ACTION_DEPRECATION_INVALID: 'an action declares a deprecation whose dates cannot be rendered',
-  X_ACTION_PATH_DUPLICATE: 'two actions derive one HTTP path',
-  X_ACTION_FOREIGN: 'a value that is not an action was projected as one',
-  X_ACTION_POLICY_MISSING: 'an action was registered without a policy',
-  X_ACTION_UNREGISTERED: 'an action was projected before it was registered',
-  X_CONTRACT_DRIFT: 'client and server disagree about the contract',
-  X_IDEMPOTENCY_CONFLICT: 'idempotency key reused with a different payload or still in flight',
-  X_IDEMPOTENCY_KEY_INVALID: 'an Idempotency-Key was sent that cannot identify one request',
-  X_IDEMPOTENCY_NOT_SHARED:
-    'idempotency is declared fleet-wide and the installed store is per-process',
-  X_IDEMPOTENCY_REPLAYED_FAILURE:
-    'a retried Idempotency-Key replays a first attempt that failed after it may have committed',
-  X_IDEMPOTENCY_STATUS_UNKNOWN: 'an idempotency record holds a status this build cannot read',
-  X_INPUT_INVALID: 'input failed schema validation',
-  X_MUTATOR_CLOCK_MISSING:
-    "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"
-// from an X_ERROR_CODE_DUPLICATE at import into whichever module loaded first deciding the title.
-registerErrorCodes(
-  Object.fromEntries(Object.entries(OWNED_TITLES).map(([code, title]) => [code, { title }])),
-);
-
 /** Thrown when a projection needs a name the action does not have yet. */
 export class ActionUnregisteredError extends UltimateError {
   constructor() {
@@ -124,7 +92,7 @@ export function denialReason(denial: SurfaceDenial): string {
 }
 
 /**
- * An authz denial, thrown by `guard()`. The code and reason come from the policy
+ * An authz denial, thrown by `guardAction()`. The code and reason come from the policy
  * decision — this package never invents an authz code — and the surface-shaped
  * denial rides along for projections that render it themselves.
  */
@@ -219,7 +187,7 @@ export class InputInvalidError extends UltimateError {
     super({
       code: 'X_INPUT_INVALID',
       cause: `input for ${subject} "${name}" failed validation: ${detail}`,
-      fix: `x actions describe ${name} --json  # prints the expected input schema`,
+      fix: `x actions describe ${renderFixShellArg(name, '<action-name>')} --json  # prints the expected input schema`,
       // A remote caller holds the published schema — the MCP `inputSchema`, the OpenAPI request
       // body — and cannot run `x actions describe`.
       callerFix:
@@ -240,7 +208,7 @@ export class OutputInvalidError extends UltimateError {
     super({
       code: 'X_OUTPUT_INVALID',
       cause: `action "${name}" returned a value its output schema rejects: ${detail}`,
-      fix: `x actions describe ${name} --json  # compare the handler's return against \`output:\``,
+      fix: `x actions describe ${renderFixShellArg(name, '<action-name>')} --json  # compare the handler's return against \`output:\``,
     });
   }
 }
@@ -289,6 +257,13 @@ export interface RemoteFailure {
    * so an island reads `error.meta.sessionId` where it used to run a regex over `cause`.
    */
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * The document's `title`, already read by core's `remoteTitleOf` — used only when this bundle
+   * registered no title for `code`, which is every http refusal in an island.
+   */
+  readonly title?: string | undefined;
+  /** The delay the answer's `Retry-After` named, in seconds (core's `retryAfterSecondsOf`). */
+  readonly retryAfterSeconds?: number | undefined;
 }
 
 /** A link, not a string the server happened to put in a field the overlay renders as an href. */
@@ -341,19 +316,27 @@ export class RemoteActionError extends UltimateError {
       // this build may never have heard of. `UltimateError` otherwise fills `retry` from
       // `retryFor(code)`, which fails closed — so a 503 out of a typed call announced itself as
       // `terminal` on the one field the framework promises a client never has to infer.
-      retry: retryForStatus(failure.code, failure.status),
-      meta: {
-        // The server's declared keys FIRST, so the four this class owns win a collision: a server
-        // meta naming `status` would otherwise overwrite the one a report reads the HTTP status
-        // from, and `origin: 'remote'` is what marks the code as one this bundle never declared.
-        ...failure.meta,
-        origin: 'remote',
-        action: failure.action,
-        status: failure.status,
-        // Absent rather than `undefined`: `meta` is rendered into `--json` and the error reporter,
-        // and a null member reads as "the server sent an empty list" rather than "it sent none".
-        ...(failure.issues === undefined ? {} : { issues: failure.issues }),
-      },
+      // A 429 or 503 that stated a delay is `retry-after` whoever registered the code, and the
+      // delay rides on `meta.retryAfterSeconds`, the one key core's `statedDelayMs` reads.
+      retry: retryForStatus(failure.code, failure.status, failure.retryAfterSeconds),
+      remoteTitle: failure.title,
+      // Core's `withStatedDelay`, the rule `problemError` applies too: a `retryAfterSeconds` off the
+      // body is dropped and only the header's is carried — the server never writes one there.
+      meta: withStatedDelay(
+        {
+          // The server's declared keys FIRST, so the four this class owns win a collision: a
+          // server meta naming `status` would otherwise overwrite the one a report reads the HTTP
+          // status from, and `origin: 'remote'` marks the code as one this bundle never declared.
+          ...failure.meta,
+          origin: 'remote',
+          action: failure.action,
+          status: failure.status,
+          // Absent rather than `undefined`: `meta` is rendered into `--json` and the error
+          // reporter, and a null member reads as "the server sent an empty list".
+          ...(failure.issues === undefined ? {} : { issues: failure.issues }),
+        },
+        failure.retryAfterSeconds,
+      ),
     });
     this.status = failure.status;
   }
@@ -370,7 +353,7 @@ export class RpcFailedError extends UltimateError {
     super({
       code: 'X_RPC_FAILED',
       cause: `${name} returned HTTP ${status} without a problem+json body`,
-      fix: `check the gateway in front of the app, then: x actions describe ${name} --json`,
+      fix: `check the gateway in front of the app, then: x actions describe ${renderFixShellArg(name, '<action-name>')} --json`,
       retry: retryForStatus('X_RPC_FAILED', status),
     });
   }
@@ -388,7 +371,7 @@ export class AuditSinkMissingError extends UltimateError {
     super({
       code: 'X_AUDIT_SINK_MISSING',
       cause: `action "${action}" declares \`audit: true\` and no audit sink is installed`,
-      fix: "call setAuditSink(yourSink) from '@ultimat3/action' at boot, before registerActions()",
+      fix: "call setAuditSink(yourSink) from '@ultimat3/core' at boot, before registerActions()",
     });
   }
 }

package/src/facade.ts

@@ -1,9 +1,10 @@
 /**
- * The fluent surface: every projection reachable as a method on the action itself,
- * `publishPost.tool()` rather than `toMcpTool(publishPost)`, and every declared
- * field lifted off `def` so app code never reaches through `.def`. The projection
- * functions stay exported for the framework's own call sites — this file only
- * binds them to the action, it never re-implements one.
+ * The fluent surface: every projection this package owns reachable as a method on the action
+ * itself, `publishPost.openapi()` rather than `toOpenApiOperation(publishPost)`, and every
+ * declared field lifted off `def` so app code never reaches through `.def`. The projection
+ * functions stay exported for the framework's own call sites — this file only binds them to the
+ * action, it never re-implements one. There is no `.tool()`: the MCP tool is `@ultimat3/mcp`'s
+ * one projection (`toolFrom(publishPost)`), a tier this package cannot import.
  */
 
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
@@ -13,7 +14,6 @@ import { contractTestsFor } from './contract-test';
 import { toOpenApiOperation } from './http';
 import { actionName, invoke } from './invoke';
 import { toJobHandle } from './job-handle';
-import { toMcpTool } from './mcp-tool';
 
 /**
  * `self` is a thunk on purpose: the façade is attached while the action is still
@@ -33,7 +33,6 @@ export function facadeFor<TInput extends StandardSchemaV1, TOutput extends Stand
     // the output type is this action's by construction.
     as: (actor, input, options) =>
       invoke(self(), input, { ...options, actor }) as Promise<InferOutput<TOutput>>,
-    tool: () => toMcpTool(self()),
     openapi: () => toOpenApiOperation(self()),
     client: (options) => clientMethodFor(actionName(self()), options, def.http?.path),
     job: () => toJobHandle(self()),

package/src/http-path.ts

@@ -69,7 +69,7 @@ export function setActionPathStyle(next: unknown): ActionPathStyle {
   return style;
 }
 
-/** Test seam, beside `resetRegistry`. */
+/** Test seam, beside `resetActions`. */
 /**
  * Forget which paths were handed out, keeping the style. `@ultimat3/testing` calls it between two
  * test files of one worker (22.7, no `--isolate`): a path an earlier FILE derived is not one this

package/src/http.ts

@@ -6,10 +6,15 @@
  */
 
 import { tagKeys } from '@ultimat3/cache';
+import type { Deprecation } from '@ultimat3/core';
 import {
+  IDEMPOTENCY_HEADER,
   isMcpExposed,
   RECORDS_OPENAPI_HEADER,
+  recordDeprecatedCall,
   recordEnvelopeSchema,
+  renderDeprecation,
+  useContext,
   withWriteOrigin,
   writeDigest,
 } from '@ultimat3/core';
@@ -17,10 +22,9 @@ import type { Route, RouteMeta, UltimateRequest } from '@ultimat3/http';
 // `toBucket` is `@ultimat3/http`'s, not this package's: http owns `Bucket` and the limiter maths,
 // and `@ultimat3/query` needs the identical conversion while being the same tier as this one — so
 // a copy here would be a second answer to "what does this limit mean" for the read half.
-import { json, redirect, takeRedirect, toBucket } from '@ultimat3/http';
+import { jsonResponse, publishRateLimit, redirect, takeRedirect, toBucket } from '@ultimat3/http';
+import { admitsAnonymous, policyCapability, policyPermissions } from '@ultimat3/policy';
 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';
@@ -31,16 +35,7 @@ import {
   schemaRef,
   toOperationId,
 } from './naming';
-import { admitsAnonymous, policyCapability, policyPermissions } from './policy-gate';
 import { carriesRecords, recordResponse } from './record-wire';
-import { IDEMPOTENCY_HEADER } from './wire-headers';
-
-/**
- * Re-exported, never re-declared. The two strings moved to `wire-headers.ts` so `client.ts` can
- * name them without pulling this file's server graph into a browser bundle; every importer of
- * `./http` still reads them from here, which is what kept the move from touching a call site.
- */
-export { BUILD_ID_HEADER, IDEMPOTENCY_HEADER } from './wire-headers';
 
 export const REPLAYED_HEADER = 'x-ultimate-replayed';
 
@@ -90,6 +85,9 @@ function projectRoute(
   // 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.
   const sunsetting = deprecationHeadersFor(name, def.deprecated);
+  // Same rule, for a limit the limiter could not run on: refused at mount (`X_RATE_LIMIT_INVALID`),
+  // never on the first request that tries to spend it.
+  if (def.rateLimit !== undefined) toBucket(name, def.rateLimit);
   const enveloped = carriesRecords(target.output);
 
   const handler = async (req: UltimateRequest): Promise<Response> => {
@@ -121,6 +119,9 @@ function projectRoute(
         onReplay: () => {
           replayed = true;
         },
+        clientAddress: req.ctx.ip,
+        onRateLimit: (decision) =>
+          publishRateLimit(req.ctx, decision, useContext().now().getTime()),
       }),
     );
     // The one thing an action's return value cannot say. `setRedirect()` inside the handler
@@ -134,7 +135,7 @@ function projectRoute(
         ? redirect(to.location, to.status)
         : enveloped
           ? recordResponse(target.output, result)
-          : json(result);
+          : jsonResponse(result);
     if (key !== null) response.headers.set(REPLAYED_HEADER, replayed ? '1' : '0');
     return response;
   };
@@ -154,6 +155,9 @@ function projectRoute(
     // stage deciding first would decide from `row: null` — a denial for the row's own
     // author, from an authz system that never saw the row.
     enforcedBy: 'handler',
+    // Which primitive this is, for `@ultimat3/http`'s bucket check: a `rateLimit.buckets.<name>`
+    // named after an action limits nothing since 25.0.0, and is refused rather than ignored.
+    primitive: 'action',
     // `input` stays ABSENT, deliberately, exactly as `@ultimat3/query`'s `toQueryRoute` leaves it.
     // Setting it hands the action's schema to the pipeline's `body` stage, which throws
     // `bodyInvalid` — so this route answered `422 X_BODY_INVALID` for every malformed body while
@@ -167,12 +171,11 @@ function projectRoute(
     // failing a plain `route.ts`'s own schema, where no primitive owns the input.
     cache: { mode: 'no-store', tags: tagKeys(def.cache?.invalidates ?? []) },
     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.
-    ...(def.rateLimit === undefined
-      ? {}
-      : { rateLimit: name, rateLimitBucket: toBucket(name, def.rateLimit) }),
+    // `invoke` spends the declared bucket for every surface, so the stage spends no caller bucket
+    // for this route — not the action's (that was the second, HTTP-only enforcement point MCP,
+    // the agent tool and `.job()` never reached) and not `default` (a ceiling an action declaring
+    // more than it never had). The tenant allowance is still the stage's.
+    ...(def.rateLimit === undefined ? {} : { rateLimitedBy: 'handler' as const }),
     ...(def.mcp?.description === undefined ? {} : { description: def.mcp.description }),
   };
 
@@ -254,7 +257,7 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
       invalidates: tagKeys(def.cache?.invalidates ?? []),
       // The tool name an agent would call, or `null` when there is no tool. `!== false` here
       // advertised one for every action, so an agent reading the spec asked for a tool the MCP
-      // catalog never listed — `isMcpExposed` is the same answer `toMcpTool` gives. The NAME was
+      // catalog never listed — `isMcpExposed` is the same answer `@ultimat3/mcp` gives. The NAME was
       // the second half of the same defect: `toToolName` published `publish_post` while
       // `@ultimat3/mcp` served `publishPost`, so a spec-reading agent called a tool that does not
       // exist. Verbatim, and never derived — this is a published contract, not a label.