@ultimat3/http 23.0.0 → 25.0.0

package/src/rate-limit-postgres.ts

@@ -1,26 +1,13 @@
-// The shared rate-limit store: one Postgres table, one `insert … on conflict` per take, so N
-// replicas count against one bucket. Without it `config.rateLimit.scope: 'shared'` is a
-// declaration nothing can satisfy while `docker/helm/values.yaml` runs `roles.web.replicas: 3`.
+// The shared rate-limit store: one Postgres table, one `insert … on conflict` per take and a plain
+// `select` per peek, so N replicas count against one bucket. Without it `rateLimit.scope: 'shared'`
+// is a declaration nothing can satisfy while `docker/helm/values.yaml` runs `replicas: 3`.
 // Statements are spelled out so an agent can run the exact one it saw in a log.
 
+import type { PgExecutor } from '@ultimat3/core';
 import type { RateLimitDecision, RateLimitScope, RateLimitStore } from './rate-limit';
 import { rateLimitDecision } from './rate-limit';
 import { rateLimitStoreUnavailable } from './rate-limit-errors';
-
-/**
- * The one thing this store needs from the DB layer, declared structurally rather than imported —
- * `@ultimat3/action`'s `idempotency-postgres.ts` and `@ultimat3/jobs` declare the same shape for
- * the same reason: neither package owns the other's connection. Here it is also the only option:
- * `@ultimat3/http` has no `@ultimat3/db` dependency at all, and taking one to type a single method
- * would put the whole database package in this package's install graph.
- *
- * **`Bun.sql` does not satisfy it** — `Bun.sql.query` is `undefined`; it is a tagged template whose
- * positional form is `unsafe`. What satisfies it is a client that already speaks `(text, values)`,
- * wrapped in one line — `@ultimat3/db`'s `DbClient.query({ text, values })` is the framework's own.
- */
-export interface PgExecutor {
-  query<R>(sql: string, params: readonly unknown[]): Promise<readonly R[]>;
-}
+import { rateLimitPeek, refilledTokens } from './rate-limit-peek';
 
 /**
  * Installed by the boot, not by an app migration — the same rule `SQL_IDEMPOTENCY_TABLE` follows,
@@ -93,6 +80,13 @@ returning tokens, spent
 
 export const SQL_RATE_LIMIT_RESET = 'delete from x_rate_limit where key = $1';
 
+/**
+ * `peek`: a plain read, never the upsert — it runs on every request to a required route, and a
+ * write there was a row lock and a WAL record per signed-in page. The refill is computed in JS
+ * from the row by `refilledTokens`, the memory store's own arithmetic; no row means full.
+ */
+export const SQL_RATE_LIMIT_PEEK = 'select tokens, last_ms from x_rate_limit where key = $1';
+
 /**
  * The memory store's forget rule, in SQL: a bucket back at capacity answers exactly as a missing
  * one, so dropping it changes no decision. A bucket that never refills
@@ -114,6 +108,12 @@ delete from x_rate_limit
          * refill_per_second >= capacity
 `;
 
+interface PeekRow {
+  /** `double precision` / `bigint`, which some clients hand back as strings. */
+  readonly tokens: number | string;
+  readonly last_ms: number | string;
+}
+
 interface TakeRow {
   /** `double precision`, which some clients hand back as a string. */
   readonly tokens: number | string;
@@ -135,7 +135,7 @@ export interface PostgresRateLimitStore extends RateLimitStore {
    *
    * `nowMs` is required and comes from the SAME clock the takes use — `ctx.now().getTime()` in a
    * task. There is no default, because the only defensible default would be this process' own
-   * `Date.now()`, and a store that reads a clock nobody handed it is the thing `createRateLimiter`
+   * `Date.now()`, and a store that reads a clock nobody handed it is the thing `rateLimiter`
    * took a `Clock` to stop.
    */
   purgeExpired(nowMs: number): Promise<number>;
@@ -150,14 +150,14 @@ export interface PostgresRateLimitStore extends RateLimitStore {
  *
  * // apps/web/server.ts — what PROVIDES it
  * const client = db();
- * createServer({
+ * httpServer({
  *   rateLimitStore: postgresRateLimitStore({
  *     executor: { query: (text, values) => client.query({ text, values }) },
  *   }),
  * });
  * ```
  *
- * `assertRateLimitScope` compares the two once, inside `createPipeline`, and a `'shared'`
+ * `assertRateLimitScope` compares the two once, inside `httpPipeline`, and a `'shared'`
  * declaration over any other store is `X_RATE_LIMIT_NOT_SHARED` before the socket opens.
  */
 export function postgresRateLimitStore(
@@ -184,6 +184,15 @@ export function postgresRateLimitStore(
       return rateLimitDecision(bucket, Number(row.tokens), cost, isTrue(row.spent), nowMs);
     },
 
+    async peek(key, bucket, nowMs) {
+      const row = (await exec.query<PeekRow>(SQL_RATE_LIMIT_PEEK, [key]))[0];
+      const tokens =
+        row === undefined
+          ? bucket.capacity
+          : refilledTokens(bucket, Number(row.tokens), Number(row.last_ms), Math.floor(nowMs));
+      return rateLimitPeek(bucket, tokens);
+    },
+
     async reset(key): Promise<void> {
       await exec.query(SQL_RATE_LIMIT_RESET, [key]);
     },

package/src/rate-limit-stage.ts

@@ -0,0 +1,132 @@
+// What the pipeline SPENDS, and when: the `rate-limit` stage's list of keys for a request that
+// has a caller, and the one allowance the `auth` stage spends for a request that failed to have
+// one. Split out of `stages.ts` at the size ceiling; the bucket maths stays in `rate-limit.ts`.
+
+import { actorView, type RequestContext } from './context';
+import {
+  type RateLimitConfig,
+  type RateLimitDecision,
+  type RateLimiter,
+  type RateLimitSpend,
+  rateLimitSpends,
+} from './rate-limit';
+import { rateLimited } from './rate-limit-errors';
+
+/**
+ * The namespace failed credentials are counted in. Not route-scoped, for `TENANT_SCOPE`'s reason:
+ * a per-route key would hand one address its whole allowance again on every required route.
+ */
+export const UNAUTHENTICATED_SCOPE = 'unauthenticated';
+
+/**
+ * Spends each key in order and stops at the first refusal, so a caller its own bucket already
+ * refused costs its tenant nothing. Recorded on the context BEFORE the throw, so the 429 carries
+ * `Retry-After` and the `RateLimit-*` headers rather than making the client guess.
+ */
+const spendAll = async (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  spends: readonly RateLimitSpend[],
+): Promise<void> => {
+  let answer: RateLimitDecision | undefined;
+  let refusedKey: string | undefined;
+  for (const spend of spends) {
+    const decision = await limiter.check(spend.key, spend.bucket);
+    // The bucket closest to refusing is the one the caller has to plan against: reporting
+    // `remaining: 99` off a per-actor bucket while the tenant's holds 2 is a number that tells a
+    // client it may proceed and then refuses its next call.
+    if (answer === undefined || decision.remaining < answer.remaining) answer = decision;
+    if (!decision.allowed) {
+      answer = decision;
+      refusedKey = spend.key;
+      break;
+    }
+  }
+  if (answer === undefined) return;
+  ctx.rateLimit = answer;
+  for (const [name, value] of Object.entries(limiter.headers(answer))) {
+    ctx.headers.set(name, value);
+  }
+  if (refusedKey !== undefined) throw rateLimited(refusedKey, answer.retryAfterSeconds);
+};
+
+/**
+ * The `rate-limit` stage. A LIST, and the second entry is why: the key builder used to pick ONE
+ * subject — actor > org > ip, exclusive — so an authenticated request never touched a tenant
+ * bucket and one org's 8,000 seats each ran their own allowance against one shared pool.
+ */
+export const spendRequestBuckets = async (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  config: RateLimitConfig,
+  routeName: string,
+): Promise<void> => {
+  if (!config.enabled) return;
+  const actor = actorView(ctx.actor);
+  await spendAll(
+    ctx,
+    limiter,
+    rateLimitSpends(
+      { actorId: actor?.id ?? null, orgId: actor?.orgId ?? null, ip: ctx.ip, routeName },
+      { route: routeBucketOf(ctx, config), tenant: config.tenantBucket },
+    ),
+  );
+};
+
+/**
+ * The ONE place that decides which bucket a route's caller spends here. A route whose handler
+ * spends its own declared limit (`rateLimitedBy: 'handler'` — every action and query route, whose
+ * primitive counts that limit on every surface) spends none: `default` beside it would cap an
+ * action that declared 1,000 at 120, which a declared limit never was.
+ */
+const routeBucketOf = (ctx: RequestContext, config: RateLimitConfig): string | null => {
+  const meta = ctx.route?.meta;
+  if (meta?.rateLimitedBy === 'handler') return null;
+  return meta?.rateLimit ?? config.defaultBucket;
+};
+
+/** The one key failed credentials are counted under: the address alone, never the route. */
+const unauthenticatedKey = (ip: string | null): string =>
+  `${UNAUTHENTICATED_SCOPE}|ip:${ip ?? 'unknown'}`;
+
+/**
+ * The `auth` stage's GATE, before `authenticate()` on a required route: an address whose failure
+ * allowance is spent is refused here, a valid credential included. Spending only on failure
+ * answered a wrong guess 429 and still served a right one, so it bounded nothing a guesser cares
+ * about — and every refused guess was still a credential-store read.
+ *
+ * READ ONLY: `RateLimitStore.peek`, never a take — this runs on every request to a required route,
+ * signed-in ones included, and a zero-cost take was a Postgres upsert on each. The refusal carries
+ * the peek's own `Retry-After` (`rateLimitPeek`). With no address there is no key
+ * worth refusing on — `ip:unknown` is everyone at once — so the gate stands aside and the failure
+ * path below still counts.
+ */
+export const refuseExhaustedAddress = async (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  config: RateLimitConfig,
+): Promise<void> => {
+  if (!config.enabled || ctx.ip === null) return;
+  const key = unauthenticatedKey(ctx.ip);
+  const peek = await limiter.peek(key, config.defaultBucket);
+  if (peek.remaining >= 1) return;
+  throw rateLimited(key, peek.retryAfterSeconds);
+};
+
+/**
+ * The `auth` stage's failure path. A request refused 401 never reaches `rate-limit`, so nothing
+ * metered it: a caller with no credential, or a wrong one, could ask the credential store about
+ * tokens without bound. Spent only on FAILURE and keyed on the address ALONE — a signed-in
+ * caller behind the same NAT spends nothing here. Once it is spent, `refuseExhaustedAddress`
+ * refuses that address on required routes, signed-in callers included, until it refills.
+ */
+export const spendUnauthenticated = (
+  ctx: RequestContext,
+  limiter: RateLimiter,
+  config: RateLimitConfig,
+): Promise<void> => {
+  if (!config.enabled) return Promise.resolve();
+  return spendAll(ctx, limiter, [
+    { key: unauthenticatedKey(ctx.ip), bucket: config.defaultBucket },
+  ]);
+};

package/src/rate-limit.ts

@@ -1,6 +1,6 @@
 // Token-bucket rate limiting. The store is an interface so the same limiter runs in-memory in
 // dev/tests and against a shared tier in a multi-replica deployment — installed through
-// `createServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
+// `httpServer({ rateLimitStore })`, and refused at boot when its scope cannot keep the app's
 // declaration; the bucket maths lives here so every driver agrees on the numbers.
 import { type Clock, systemClock } from '@ultimat3/core';
 import { httpCountInvalid } from './errors';
@@ -11,6 +11,8 @@ import {
   rateLimitScopeUnset,
   tenantBucketUnknown,
 } from './rate-limit-errors';
+import { rateLimitHeaders } from './rate-limit-headers';
+import { type RateLimitPeek, rateLimitPeek, refilledTokens } from './rate-limit-peek';
 
 /**
  * Where a limiter's counters live. A store says which it provides; `RateLimitConfig` says which
@@ -36,6 +38,12 @@ export interface RateLimitStore {
   /** Declared, never inferred: a driver knows where its counters live; nothing else does. */
   readonly scope: RateLimitScope;
   take(key: string, bucket: Bucket, cost: number, nowMs: number): Promise<RateLimitDecision>;
+  /**
+   * What `key` holds NOW, refill applied — READ ONLY: no write, no row, no entry created. A key
+   * never taken is full. Required, because the `auth` stage asks it on every request to a required
+   * route, and a zero-cost `take` there was a Postgres upsert on every signed-in page.
+   */
+  peek(key: string, bucket: Bucket, nowMs: number): Promise<RateLimitPeek>;
   reset(key: string): Promise<void>;
 }
 
@@ -298,6 +306,14 @@ export const memoryRateLimitStore = (
       if (buckets.size > maxKeys || nowMs - lastSweepMs >= SWEEP_EVERY_MS) sweep(nowMs);
       return Promise.resolve(decision);
     },
+    peek(key, bucket, nowMs) {
+      const state = buckets.get(key);
+      const tokens =
+        state === undefined
+          ? bucket.capacity
+          : refilledTokens(bucket, state.tokens, state.lastMs, nowMs);
+      return Promise.resolve(rateLimitPeek(bucket, tokens));
+    },
     reset(key) {
       buckets.delete(key);
       return Promise.resolve();
@@ -310,6 +326,13 @@ export interface RateLimitKeyParts {
   readonly orgId: string | null;
   readonly ip: string | null;
   readonly routeName: string;
+  /**
+   * The subject when there is no actor, no org AND no address. Defaults to `ip:unknown` — every
+   * such request shares it, which is what the pipeline has always done. A caller that can name a
+   * narrower population (a job run nobody attributed) passes its own, so it does not share one
+   * bucket with every anonymous request whose address could not be read.
+   */
+  readonly unattributed?: string | undefined;
 }
 
 /**
@@ -345,17 +368,20 @@ export interface RateLimitSpend {
  */
 export const rateLimitSpends = (
   parts: RateLimitKeyParts,
-  buckets: { readonly route: string; readonly tenant: string | null },
+  // `route: null` — the route's own limit is spent by its handler (`RouteMeta.rateLimitedBy`), so
+  // the caller key is not spent here at all; only the tenant allowance is.
+  buckets: { readonly route: string | null; readonly tenant: string | null },
 ): readonly RateLimitSpend[] => {
   const subject =
     parts.actorId !== null
       ? `actor:${parts.actorId}`
       : parts.orgId !== null
         ? `org:${parts.orgId}`
-        : `ip:${parts.ip ?? 'unknown'}`;
-  const spends: RateLimitSpend[] = [
-    { key: `${parts.routeName}|${subject}`, bucket: buckets.route },
-  ];
+        : parts.ip !== null
+          ? `ip:${parts.ip}`
+          : (parts.unattributed ?? 'ip:unknown');
+  const spends: RateLimitSpend[] =
+    buckets.route === null ? [] : [{ key: `${parts.routeName}|${subject}`, bucket: buckets.route }];
   if (buckets.tenant !== null && parts.orgId !== null) {
     spends.push({ key: `${TENANT_SCOPE}|org:${parts.orgId}`, bucket: buckets.tenant });
   }
@@ -368,8 +394,8 @@ export interface RateLimiter {
   /**
    * The table this limiter resolves a bucket NAME against. Declared, never inferred — the same
    * rule as `RateLimitStore.scope` and `@ultimat3/auth`'s `AuthLimiter.policy`, and for the same
-   * reason: `createRateLimiter` closes over its config, so nothing outside can see which buckets
-   * it actually holds. `createPipeline` compares this against the buckets the ROUTES declare, and
+   * reason: `rateLimiter` closes over its config, so nothing outside can see which buckets
+   * it actually holds. `httpPipeline` compares this against the buckets the ROUTES declare, and
    * an unknown name is refused instead of falling through `bucketFor` to `default`.
    *
    * Optional only so an existing external implementation still type-checks; an absent table
@@ -377,12 +403,14 @@ export interface RateLimiter {
    */
   readonly buckets?: Readonly<Record<string, Bucket>> | undefined;
   check(key: string, bucketName: string, cost?: number): Promise<RateLimitDecision>;
+  /** The store's read-only `peek`, against the named bucket. Spends nothing, writes nothing. */
+  peek(key: string, bucketName: string): Promise<RateLimitPeek>;
   headers(decision: RateLimitDecision): Record<string, string>;
   /** Throws `X_RATE_LIMITED` when the bucket is empty. */
   assert(key: string, bucketName: string, cost?: number): Promise<RateLimitDecision>;
 }
 
-export const createRateLimiter = (options: {
+export const rateLimiter = (options: {
   config: RateLimitConfig;
   store?: RateLimitStore;
   /**
@@ -390,7 +418,7 @@ export const createRateLimiter = (options: {
    * BOTH production call sites (`server.ts`, `pipeline.ts`) build their limiter without an
    * override — so the limiter that actually throttles requests could not be frozen by any test,
    * while `@ultimat3/auth`'s credential limiter has taken an injected `Clock` since it shipped.
-   * Defaulted rather than required, the same shape as `createRequestContext`'s `init.clock`;
+   * Defaulted rather than required, the same shape as `requestContext`'s `init.clock`;
    * `PipelineDeps.limiter` stays the one seam for handing the pipeline a limiter of your own,
    * because a second `clock` beside it would be a second way to set one number.
    */
@@ -420,11 +448,8 @@ export const createRateLimiter = (options: {
     // no other way to learn what this limiter can enforce.
     buckets: options.config.buckets,
     check,
-    headers: (decision) => ({
-      'ratelimit-limit': String(decision.limit),
-      'ratelimit-remaining': String(decision.remaining),
-      'ratelimit-reset': String(Math.ceil((decision.resetAtMs - now()) / 1000)),
-    }),
+    peek: (key, bucketName) => store.peek(key, bucketFor(bucketName), now()),
+    headers: (decision) => rateLimitHeaders(decision, now()),
     async assert(key, bucketName, cost = 1) {
       const decision = await check(key, bucketName, cost);
       if (!decision.allowed) throw rateLimited(key, decision.retryAfterSeconds);

package/src/request-facts.ts

@@ -0,0 +1,44 @@
+// How one request arrived, as the frozen facts a token resolver is handed — never the raw
+// `Headers`. A resolver given the headers would read `x-forwarded-for` itself and trust a hop the
+// host never declared; the address here is the one the pipeline already resolved (`ctx.ip`).
+// One shape for every bearer surface: this mount, and `@ultimat3/mcp`'s `POST /mcp`.
+
+/**
+ * The request, as far as a credential decision may read it. Four facts and no more: a token bound
+ * to a network reads `address`, a resolver refusing browsers reads `origin`. Never the body (it is
+ * unread when the token is decided) and never another header — `Authorization` is the token itself.
+ */
+export interface RequestFacts {
+  /**
+   * The caller's address AS THE HOST RESOLVED IT — `ctx.ip`, a declared proxy's `x-forwarded-for`
+   * honoured per `trustedProxyHops`, else the socket. `null` when the host resolved none: a surface
+   * that cannot tell a trusted hop from a forged one never derives one from a header.
+   */
+  readonly address: string | null;
+  /** `User-Agent`, verbatim — caller-controlled, so a hint for a rule and never an identity. */
+  readonly userAgent: string | null;
+  /**
+   * The `Origin` request header: which web origin a BROWSER says is calling. `null` when absent —
+   * every non-browser client — and the literal string `'null'` for an opaque origin, which is a
+   * different fact (a sandboxed frame or a `file:` page) and must not read as "no browser".
+   */
+  readonly origin: string | null;
+  /** The URL path the request was sent to. No query string. */
+  readonly path: string;
+}
+
+export interface RequestFactsInput {
+  readonly headers: Headers;
+  readonly url: URL | string;
+  /** What the host resolved — `ctx.ip`, or a transport's `seen.address`. Never a header read. */
+  readonly address: string | null | undefined;
+}
+
+export function requestFacts(input: RequestFactsInput): RequestFacts {
+  return Object.freeze({
+    address: input.address ?? null,
+    userAgent: input.headers.get('user-agent'),
+    origin: input.headers.get('origin'),
+    path: (typeof input.url === 'string' ? new URL(input.url) : input.url).pathname,
+  });
+}

package/src/request.ts

@@ -3,12 +3,11 @@
 // context so they cannot drift from what the pipeline resolved.
 
 import type { Actor } from '@ultimat3/core';
-import { readWithinLimit, renderThrowable } from '@ultimat3/core';
+import { readCookie, readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { RequestContext } from './context';
 import { bodyInvalid, buildSkew } from './errors';
-import { readCookie } from './locale';
 import type { Schema } from './validate';
-import { validate, validateSync } from './validate';
+import { validateBody, validateSync } from './validate';
 
 export type QueryValues = Readonly<Record<string, string | readonly string[]>>;
 
@@ -153,7 +152,7 @@ export class UltimateRequest {
   }
 
   async body<Out>(schema: Schema<Out>): Promise<Out> {
-    const outcome = await validate(schema, await this.bodyRaw());
+    const outcome = await validateBody(schema, await this.bodyRaw());
     if (!outcome.ok) throw bodyInvalid(this.pathname, outcome.issues);
     return outcome.value;
   }
@@ -203,7 +202,15 @@ export class UltimateRequest {
     // An EMPTY form is a form with no fields, never "no input": a button-only `<form>` posts
     // `content-length: 0`, and reading that as `undefined` failed every schema with 400.
     const form = type === 'application/x-www-form-urlencoded' || type === 'multipart/form-data';
-    if (type === '') return undefined;
+    // No declared type is only "no body" when there are no bytes. `{"a":1}` sent bare used to
+    // read as `undefined`, so a schema whose fields are all optional validated a request nobody
+    // parsed. `bodyBytes()` stays the door for a body that is bytes by design (a signed upload).
+    if (type === '') {
+      if (declared === 0 || (await this.bodyBytes()).byteLength === 0) return undefined;
+      throw bodyInvalid(this.pathname, [
+        'the request carries a body and no content-type header saying what it is',
+      ]);
+    }
     // A multipart body is only a FORM with the boundary its header must announce. Checked before
     // the empty-form shortcut below, so a zero-length body cannot launder a malformed header into
     // `{}` — without it the parser would have refused, and an empty body must refuse the same.

package/src/response.ts

@@ -14,13 +14,13 @@ const withDefaults = (init: HeaderSource, defaults: Record<string, string>): Hea
   return headers;
 };
 
-export const json = <T>(body: T, init?: ResponseInit): Response =>
+export const jsonResponse = <T>(body: T, init?: ResponseInit): Response =>
   new Response(JSON.stringify(body), {
     ...init,
     headers: withDefaults(init, { 'content-type': 'application/json; charset=utf-8' }),
   });
 
-export const text = (body: string, init?: ResponseInit): Response =>
+export const textResponse = (body: string, init?: ResponseInit): Response =>
   new Response(body, {
     ...init,
     headers: withDefaults(init, { 'content-type': 'text/plain; charset=utf-8' }),
@@ -216,6 +216,14 @@ export const applyCacheHeaders = (response: Response, hint: CacheHint): Response
     response.headers.set('surrogate-key', hint.tags.join(' '));
     response.headers.set('cache-tag', hint.tags.join(','));
   }
+  // A response REWRITTEN to private or no-store may already carry keys: the `cache-headers` stage
+  // turns an `isr` document's shared header into `private` for a signed-in visitor, and the keys
+  // the render wrote beside it would stay on what is now a per-user document — purge keys an
+  // intermediary has no business storing it under.
+  if (!shared) {
+    response.headers.delete('surrogate-key');
+    response.headers.delete('cache-tag');
+  }
   // `cookie` is not optional on the shared path. A `public` response is stored by a CDN under the
   // URL, and every session in this framework travels in a cookie — so without it the first
   // signed-in render of a public page is what every later visitor is served. `SHARED_CACHE_VARY`

package/src/route-cache.ts

@@ -31,7 +31,7 @@ const DELTA_SECONDS_FIELDS = [
  * CLI's authorized-object hint all carry `maxAgeSeconds: 0`, so a floor of 1 would refuse the
  * framework at its own boot.
  *
- * Called once per route by `createRouter`, which is the one way a `Route` becomes matchable — so
+ * Called once per route by `httpRouter`, which is the one way a `Route` becomes matchable — so
  * every hint an app can serve has been through here, including the ones `@ultimat3/cli` mints for
  * favicons, dev assets and storage objects.
  */

package/src/router.ts

@@ -5,7 +5,7 @@
 // PRECEDENCE (deterministic, tested in router.test.ts):
 //   1. static segment   `/posts/new`
 //   2. param segment    `/posts/:id`
-//   3. wildcard segment `/posts/*rest`  (matches ONE OR MORE remaining segments)
+//   3. wildcard segment `/posts/*rest`  (matches ZERO or more remaining segments)
 // Depth-first with backtracking: `/posts/new` beats `/posts/:id` even though the
 // param branch would also match, and a dead end in the static branch still falls
 // back to the param branch. Two routes that would tie are a build error
@@ -76,6 +76,21 @@ export interface RouteMeta {
    * refuses a configured bucket of the same name that says something else.
    */
   readonly rateLimitBucket?: Bucket;
+  /**
+   * `'handler'`: the handler spends this route's own declared limit — an action's `invoke`, a
+   * query's read — because the primitive counts it on every surface (HTTP, MCP, the agent tool, a
+   * job). The `rate-limit` stage then spends no caller bucket for it, only the tenant allowance:
+   * spending `default` too would cap a primitive that declared more than `default` at `default`.
+   * Set, it wins: `rateLimit`/`rateLimitBucket` name a bucket the STAGE spends, and are not read.
+   */
+  readonly rateLimitedBy?: 'handler';
+  /**
+   * The primitive this route projects, written by `@ultimat3/action`'s `toRoute` and
+   * `@ultimat3/query`'s `toQueryRoute`; absent on a plain route. Read by the bucket check
+   * (`rate-limit-buckets.ts`): since 25.0.0 a `rateLimit.buckets.<name>` named after a primitive
+   * limits nothing and is refused, and only an explicit marker can say which routes those are.
+   */
+  readonly primitive?: 'action' | 'query';
   readonly tags?: readonly string[];
   readonly description?: string;
   /**
@@ -159,7 +174,7 @@ const segmentsOf = (path: string): readonly string[] =>
     .split('/')
     .filter((segment) => segment.length > 0);
 
-export const createRouter = (routes: readonly Route[]): RouteTable => {
+export const httpRouter = (routes: readonly Route[]): RouteTable => {
   const root = node();
   for (const route of routes) {
     // Before the trie is touched: a hint that cannot be emitted is refused where it was WRITTEN,
@@ -241,19 +256,32 @@ const candidates = (
 ): void => {
   if (index === segments.length) {
     if (current.routes.size > 0) search.out.push({ node: current, params });
+    // A catch-all with an EMPTY rest: `/docs` for `/docs/*path`, after any static route at
+    // `/docs` itself. It is the path `@ultimat3/render`'s static build writes for that page
+    // (`fillPath` fills an absent rest with `''`), and its `compilePattern` matches it — a server
+    // that 404ed it served a page the export and the ISR lookup both said existed.
+    const rest = current.wildcard;
+    if (rest !== undefined && rest.node.routes.size > 0) {
+      search.out.push({ node: rest.node, params: { ...params, [rest.name]: '' } });
+    }
     return;
   }
   const segment = segments[index];
   if (segment === undefined) return;
+  // Decoded ONCE, for every branch. `undefined` is a malformed escape, which fails only the
+  // branches that needed the decoded form: the raw static lookup below still runs.
+  const decoded = decodeSegment(segment);
 
-  // Static segments are compared raw, never decoded, so a malformed escape only ever fails the
-  // branch that would have decoded it: a path that reaches no param or wildcard is the 404 it
-  // always was, and a static route still wins the precedence it always won.
-  const staticChild = current.statics.get(segment);
+  // Raw first, then the decoded spelling: a route file is named in Unicode (`precios-españa`) and
+  // `URL.pathname` encodes it (`precios-espa%C3%B1a`), so a raw-only lookup 404ed every non-ASCII
+  // literal. A static route still wins the precedence it always won.
+  const staticChild =
+    current.statics.get(segment) ??
+    (decoded !== undefined && decoded !== segment ? current.statics.get(decoded) : undefined);
   if (staticChild !== undefined) candidates(staticChild, segments, index + 1, params, search);
 
   if (current.param !== undefined) {
-    const value = decodeSegment(segment);
+    const value = decoded;
     if (value === undefined) search.undecodable ??= segment;
     else {
       const next = { ...params, [current.param.name]: value };
@@ -330,7 +358,7 @@ const paramsOf = (path: string): readonly string[] =>
     .filter((segment) => segment.startsWith(':') || segment.startsWith('*'))
     .map((segment) => segment.slice(1));
 
-/** Feeds the `/_x` dashboard, the manifest emitter and `x routes list --json`. */
+/** Feeds the `/_x` dashboard, the manifest emitter and `x routes --json`. */
 export const describeRoutes = (table: RouteTable): readonly RouteDescription[] =>
   table.routes
     .map((route) => ({