@ultimat3/action 29.3.2 → 30.0.0

package/src/meter-memory.ts

@@ -0,0 +1,124 @@
+/**
+ * The process default meter store: one bounded Map, each draw a synchronous check-and-add with no
+ * `await` between the two, so parallel calls in one process cannot overshoot. `scope: 'process'`:
+ * N replicas each holding one enforce N × every limit — the boot installs the Postgres store.
+ */
+
+import { finiteCount } from '@ultimat3/core';
+import type { MeterPeriod } from './meter';
+import { METER_PERIODS } from './meter';
+import { meterWindow } from './meter-period';
+import type { MeterDraw, MeterDrawResult, MeterKey, MeterStore } from './meter-store';
+
+/** One entry per tenant × meter × period declaration — the bound, not a cache size. */
+export const DEFAULT_MAX_METER_KEYS = 20_000;
+
+export interface MemoryMeterStoreOptions {
+  readonly maxKeys?: number;
+}
+
+interface Counter {
+  periodStartMs: number;
+  /** When `periodStartMs`'s period ends; `Infinity` for a period key this store cannot read. */
+  periodEndMs: number;
+  used: number;
+  warned: boolean;
+}
+
+const PERIODS: ReadonlySet<string> = new Set<string>(METER_PERIODS);
+
+/** `day@UTC` → the end of the period starting at `startMs`; the zone is UTC, the only one. */
+function periodEnd(period: string, startMs: number): number {
+  const name = period.split('@')[0] ?? '';
+  return PERIODS.has(name)
+    ? meterWindow(name as MeterPeriod, startMs).endMs
+    : Number.POSITIVE_INFINITY;
+}
+
+/** A JSON tuple, never a joined string: no subject or meter can forge another's key. */
+const keyOf = (key: MeterKey): string => JSON.stringify([key.subject, key.meter, key.period]);
+
+export function memoryMeterStore(options: MemoryMeterStoreOptions = {}): MeterStore {
+  const maxKeys = finiteCount(
+    'memoryMeterStore',
+    'maxKeys',
+    options.maxKeys ?? DEFAULT_MAX_METER_KEYS,
+    1,
+  );
+  const counters = new Map<string, Counter>();
+
+  /** The latest period start any draw named: a moment known to have passed, with no clock read. */
+  let passedMs = Number.NEGATIVE_INFINITY;
+
+  /**
+   * Past the bound a counter whose period already ENDED goes first — it is worth nothing — then the
+   * oldest period start, then insertion order. By start alone a live month counter went before an
+   * hour counter that had finished. Forgetting a live counter forgives that tenant's usage, which
+   * is a weaker limit in one process, never a refusal of somebody who is within theirs.
+   */
+  const evict = (): void => {
+    if (counters.size < maxKeys) return;
+    let victim: string | undefined;
+    let victimFinished = false;
+    let victimStart = Number.POSITIVE_INFINITY;
+    for (const [id, counter] of counters) {
+      const finished = counter.periodEndMs <= passedMs;
+      if (finished && !victimFinished) {
+        victim = id;
+        victimFinished = true;
+        victimStart = counter.periodStartMs;
+      } else if (finished === victimFinished && counter.periodStartMs < victimStart) {
+        victim = id;
+        victimStart = counter.periodStartMs;
+      }
+    }
+    if (victim !== undefined) counters.delete(victim);
+  };
+
+  return {
+    scope: 'process',
+
+    async draw(request: MeterDraw): Promise<MeterDrawResult> {
+      if (Number.isFinite(request.periodStartMs))
+        passedMs = Math.max(passedMs, request.periodStartMs);
+      const id = keyOf(request);
+      const existing = counters.get(id);
+      // A later period resets the count; an EARLIER one (a replica whose clock runs behind) adds to
+      // the current one — the Postgres statement's `greatest`, so both stores answer alike.
+      const current =
+        existing === undefined || request.periodStartMs > existing.periodStartMs
+          ? undefined
+          : existing;
+      const used = (current?.used ?? 0) + 1;
+      if (used > request.limit) {
+        return { allowed: false, used: current?.used ?? 0, warned: current?.warned ?? false };
+      }
+      if (current === undefined) {
+        if (existing === undefined) evict();
+        counters.set(id, {
+          periodStartMs: request.periodStartMs,
+          periodEndMs: periodEnd(request.period, request.periodStartMs),
+          used,
+          warned: false,
+        });
+        return { allowed: true, used, warned: false };
+      }
+      current.used = used;
+      return { allowed: true, used, warned: current.warned };
+    },
+
+    async claimWarning(key, periodStartMs): Promise<boolean> {
+      const counter = counters.get(keyOf(key));
+      if (counter === undefined || counter.periodStartMs !== periodStartMs || counter.warned) {
+        return false;
+      }
+      counter.warned = true;
+      return true;
+    },
+
+    async releaseWarning(key, periodStartMs): Promise<void> {
+      const counter = counters.get(keyOf(key));
+      if (counter !== undefined && counter.periodStartMs === periodStartMs) counter.warned = false;
+    },
+  };
+}

package/src/meter-period.ts

@@ -0,0 +1,34 @@
+/**
+ * Which period an instant falls in, for a meter: its start and its end, in UTC. UTC and never an
+ * ambient zone — every replica must compute the same boundary for the same instant, or two pods
+ * count one tenant's day against two different rows. The stored key names the zone (`day@UTC`),
+ * so a zone-aware period added later is a new counter, never a reinterpreted one.
+ */
+
+import type { MeterPeriod } from './meter';
+
+export interface MeterWindow {
+  readonly startMs: number;
+  readonly endMs: number;
+}
+
+const HOUR_MS = 3_600_000;
+
+export function meterWindow(period: MeterPeriod, nowMs: number): MeterWindow {
+  if (period === 'hour') {
+    const startMs = Math.floor(nowMs / HOUR_MS) * HOUR_MS;
+    return { startMs, endMs: startMs + HOUR_MS };
+  }
+  const at = new Date(nowMs);
+  const year = at.getUTCFullYear();
+  const month = at.getUTCMonth();
+  if (period === 'day') {
+    const day = at.getUTCDate();
+    return { startMs: Date.UTC(year, month, day), endMs: Date.UTC(year, month, day + 1) };
+  }
+  // `Date.UTC` normalises month 12 to January of the next year, so December needs no branch.
+  return { startMs: Date.UTC(year, month, 1), endMs: Date.UTC(year, month + 1, 1) };
+}
+
+/** The period half of the stored key — the zone spelled out so it can never be assumed. */
+export const meterPeriodKey = (period: MeterPeriod): string => `${period}@UTC`;

package/src/meter-postgres.ts

@@ -0,0 +1,132 @@
+/**
+ * The SHARED meter store: one Postgres row per tenant × meter × period declaration, one
+ * conditional `insert … on conflict` per draw, so every replica counts against one number and a
+ * restart forgets nothing. Statements are spelled out so an agent can run the exact one it saw.
+ */
+
+import type { PgExecutor } from '@ultimat3/core';
+import type { MeterDraw, MeterDrawResult, MeterKey, MeterStore } from './meter-store';
+
+/**
+ * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows.
+ *
+ * **One row per counter, rolled over in place.** The row holds the CURRENT period only: a draw in
+ * a later period resets it, so the table is bounded by tenants × meters and needs no purge — the
+ * unbounded-table cost `x_rate_limit` pays (#296) is not paid twice. Usage history is not kept:
+ * an app that bills on it records its own, which is a business table, not a counter.
+ */
+export const SQL_METER_TABLE = `
+create table if not exists x_meter (
+  subject      text        not null,
+  meter        text        not null,
+  period       text        not null,
+  period_start timestamptz not null,
+  used         bigint      not null,
+  warned       boolean     not null default false,
+  updated_at   timestamptz not null default now(),
+  primary key (subject, meter, period)
+);
+`;
+
+/**
+ * `$1` subject, `$2` meter, `$3` period key, `$4` the period start, `$5` the limit.
+ *
+ * Atomic and conditional in ONE statement: the `insert … select … where` admits a first draw only
+ * within the limit, and `do update … where` re-checks against the row AFTER its lock is taken — a
+ * direct `x_meter.used` reference, never a CTE, which would read the statement's snapshot and let
+ * two racing draws both see the last free slot. No row back means refused, and nothing changed.
+ *
+ * `period_start` only moves FORWARD (`greatest`): a replica whose clock runs behind adds to the
+ * current period instead of resetting it to the one before.
+ */
+const SQL_METER_DRAW = `
+insert into x_meter (subject, meter, period, period_start, used, warned)
+select $1, $2, $3, $4::timestamptz, 1, false
+where 1 <= $5::bigint
+on conflict (subject, meter, period) do update set
+  used = case when excluded.period_start > x_meter.period_start then 1 else x_meter.used + 1 end,
+  warned = case when excluded.period_start > x_meter.period_start then false else x_meter.warned end,
+  period_start = greatest(x_meter.period_start, excluded.period_start),
+  updated_at = now()
+where (case when excluded.period_start > x_meter.period_start then 0 else x_meter.used end) + 1
+  <= $5::bigint
+returning used, warned
+`;
+
+/** What a refused draw is told it had used — read only on a refusal, never before a draw. */
+const SQL_METER_READ = `
+select used, warned from x_meter
+where subject = $1 and meter = $2 and period = $3 and period_start >= $4::timestamptz
+`;
+
+/** Exactly one claimant per period: the `not warned` predicate under the row lock. */
+const SQL_METER_CLAIM = `
+update x_meter set warned = true
+where subject = $1 and meter = $2 and period = $3 and period_start = $4::timestamptz and not warned
+returning subject
+`;
+
+const SQL_METER_RELEASE = `
+update x_meter set warned = false
+where subject = $1 and meter = $2 and period = $3 and period_start = $4::timestamptz
+`;
+
+interface CounterRow {
+  /** `bigint`, which a client hands back as a string. */
+  readonly used: number | string;
+  /** `boolean`, which a text-mode client hands back as `'t'`. */
+  readonly warned: boolean | string;
+}
+
+export interface PostgresMeterStoreOptions {
+  readonly executor: PgExecutor;
+}
+
+const isTrue = (value: boolean | string): boolean => value === true || value === 't';
+const iso = (ms: number): string => new Date(ms).toISOString();
+const keyParams = (key: MeterKey, periodStartMs: number): readonly unknown[] => [
+  key.subject,
+  key.meter,
+  key.period,
+  iso(periodStartMs),
+];
+
+/**
+ * Installed by the CLI boot over the pool it already opened — never the open transaction's
+ * connection: a draw is the caller's whether or not the business write commits, as a handler that
+ * threw may have committed and is charged for that reason.
+ */
+export function postgresMeterStore(options: PostgresMeterStoreOptions): MeterStore {
+  const exec = options.executor;
+  return {
+    scope: 'shared',
+
+    async draw(request: MeterDraw): Promise<MeterDrawResult> {
+      const rows = await exec.query<CounterRow>(SQL_METER_DRAW, [
+        ...keyParams(request, request.periodStartMs),
+        request.limit,
+      ]);
+      const row = rows[0];
+      if (row !== undefined) {
+        return { allowed: true, used: Number(row.used), warned: isTrue(row.warned) };
+      }
+      const current = (
+        await exec.query<CounterRow>(SQL_METER_READ, keyParams(request, request.periodStartMs))
+      )[0];
+      return {
+        allowed: false,
+        used: current === undefined ? 0 : Number(current.used),
+        warned: current !== undefined && isTrue(current.warned),
+      };
+    },
+
+    async claimWarning(key, periodStartMs): Promise<boolean> {
+      const rows = await exec.query(SQL_METER_CLAIM, keyParams(key, periodStartMs));
+      return rows.length === 1;
+    },
+
+    async releaseWarning(key, periodStartMs): Promise<void> {
+      await exec.query(SQL_METER_RELEASE, keyParams(key, periodStartMs));
+    },
+  };
+}

package/src/meter-store.ts

@@ -0,0 +1,61 @@
+/**
+ * The meter store SEAM: what a counter must answer, and the installed-store slot `invoke` draws
+ * from. The process default is `memoryMeterStore()`; the boot installs `postgresMeterStore()` on
+ * the pool it opened, so a tenant's day is one counter across every replica and every restart.
+ */
+
+import { memoryMeterStore } from './meter-memory';
+
+/** One counter: whose, which meter, which period declaration. */
+export interface MeterKey {
+  /** `org:<id>`, else `actor:<id>`, else `job:unattributed` or `anonymous` — `meter-gate.ts`. */
+  readonly subject: string;
+  readonly meter: string;
+  /** `day@UTC` — the period AND its zone, so a re-declared period is a new counter. */
+  readonly period: string;
+}
+
+export interface MeterDraw extends MeterKey {
+  /** The current period's start, epoch ms. A later start than the stored one resets the count. */
+  readonly periodStartMs: number;
+  /** The allowance for THIS call, resolved by the caller: a plan change applies at once. */
+  readonly limit: number;
+}
+
+export interface MeterDrawResult {
+  /** `false`: the draw would pass `limit`, and nothing was counted. */
+  readonly allowed: boolean;
+  /** The count after this draw, or the count that refused it. */
+  readonly used: number;
+  /** Whether this period's warning was already claimed. */
+  readonly warned: boolean;
+}
+
+export interface MeterStore {
+  /** Declared, never inferred: a driver knows where its counters live. */
+  readonly scope: 'process' | 'shared';
+  /**
+   * Count one call, atomically, only while the count stays within `limit`: never a read followed
+   * by a write, so N parallel draws at the edge admit exactly the remainder.
+   */
+  draw(request: MeterDraw): Promise<MeterDrawResult>;
+  /** Claim this period's warning. `true` for exactly one caller per period. */
+  claimWarning(key: MeterKey, periodStartMs: number): Promise<boolean>;
+  /** Give a claim back — the enqueue it was for failed, so the next draw may try again. */
+  releaseWarning(key: MeterKey, periodStartMs: number): Promise<void>;
+}
+
+let installed: MeterStore = memoryMeterStore();
+
+export function setMeterStore(store: MeterStore): void {
+  installed = store;
+}
+
+export function getMeterStore(): MeterStore {
+  return installed;
+}
+
+/** Back to a fresh process default. The boot's teardown, and a test's. */
+export function resetMeterStore(): void {
+  installed = memoryMeterStore();
+}

package/src/meter.ts

@@ -0,0 +1,124 @@
+/**
+ * An action's `meter:` declaration — a durable per-period allowance drawn inside `invoke` — and the
+ * checks that refuse one that could not be enforced. The counting is `meter-gate.ts`'s; the
+ * counters are the installed `MeterStore`'s. Plans, prices and what a tenant may buy are the app's.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { renderCauseValue } from '@ultimat3/core';
+import { type Infer, t } from '@ultimat3/schema';
+import { MeterInvalidError } from './errors-meter';
+
+/** The periods a meter resets on. Boundaries are UTC (`meter-period.ts`), and the key says so. */
+export const METER_PERIODS = Object.freeze(['hour', 'day', 'month'] as const);
+
+export type MeterPeriod = (typeof METER_PERIODS)[number];
+
+/** What a call-time limit is resolved from: the caller's context, never the request. */
+export interface MeterLimitArgs {
+  readonly ctx: Ctx;
+}
+
+/** A number, or one resolved per call from `ctx` — the tenant's plan, read by the app. */
+export type ResolvedLimit = number | ((args: MeterLimitArgs) => number | Promise<number>);
+
+/**
+ * What a crossed `warnAt` hands over: one per tenant, meter and period, after the draw that
+ * crossed it landed. A schema, so the job an app declares to receive it parses the same shape.
+ */
+export const MeterWarning = t.object({
+  action: t.string,
+  meter: t.string,
+  orgId: t.nullable(t.string),
+  actorId: t.nullable(t.string),
+  used: t.number.int(),
+  limit: t.number.int(),
+  periodStart: t.string,
+  resetsAt: t.string,
+});
+
+export type MeterWarning = Infer<typeof MeterWarning>;
+
+/** How the warning is enqueued: outside the caller's transaction, attributed to its tenant. */
+export interface MeterWarnEnqueueOptions {
+  readonly outbox: false;
+  readonly tenantId?: string;
+}
+
+/**
+ * Where a crossed threshold goes — a `job()` from `@ultimat3/jobs` satisfies it as written. A
+ * structural type, because `@ultimat3/jobs` is this package's tier and can never be imported here.
+ */
+export interface MeterWarnTarget {
+  enqueue(warning: MeterWarning, options: MeterWarnEnqueueOptions): Promise<unknown>;
+}
+
+export interface ActionMeter {
+  /** The counter's name. Two actions naming one meter with one period draw on one counter. */
+  readonly name: string;
+  readonly period: MeterPeriod;
+  /** Calls allowed per period: a whole number, `0` refusing every call. */
+  readonly limit: ResolvedLimit;
+  /** The fraction of `limit` whose crossing enqueues `onWarn`, once per period. `(0, 1]`. */
+  readonly warnAt?: number;
+  /** Required with `warnAt`, and only with it. */
+  readonly onWarn?: MeterWarnTarget;
+}
+
+/** What `describe()` publishes: the declaration minus the function and the target. */
+export interface ActionMeterFact {
+  readonly name: string;
+  readonly period: MeterPeriod;
+  readonly timeZone: 'UTC';
+  /** `null` when the limit is resolved per call — no static number exists to publish. */
+  readonly limit: number | null;
+  readonly warnAt: number | null;
+}
+
+/** A meter name is a key in a durable table and a word in a cause: kept to a plain identifier. */
+const METER_NAME = /^[a-z][a-zA-Z0-9]*(?:[._-][a-zA-Z0-9]+)*$/;
+const METER_NAME_MAX = 64;
+
+const isMeterPeriod = (value: unknown): value is MeterPeriod =>
+  typeof value === 'string' && (METER_PERIODS as readonly string[]).includes(value);
+
+/** A whole, non-negative, exactly representable count of calls. */
+export const isMeterLimit = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/** At `action()`: a meter that could not be counted is refused where it is written. */
+export function assertMeterDeclaration(meter: ActionMeter): void {
+  const name: unknown = meter.name;
+  if (typeof name !== 'string' || name.length > METER_NAME_MAX || !METER_NAME.test(name)) {
+    const shown = typeof name === 'string' ? name : renderCauseValue(name);
+    throw new MeterInvalidError(shown, 'name', 'a camelCase identifier of at most 64 chars');
+  }
+  if (!isMeterPeriod(meter.period)) {
+    throw new MeterInvalidError(name, 'period', `one of ${METER_PERIODS.join(' | ')}`);
+  }
+  if (typeof meter.limit !== 'function' && !isMeterLimit(meter.limit)) {
+    throw new MeterInvalidError(name, 'limit', 'a whole number of calls, 0 or more');
+  }
+  const warnAt: unknown = meter.warnAt;
+  if (warnAt !== undefined) {
+    if (typeof warnAt !== 'number' || !Number.isFinite(warnAt) || warnAt <= 0 || warnAt > 1) {
+      throw new MeterInvalidError(name, 'warnAt', 'a fraction of the limit in (0, 1]');
+    }
+  }
+  // Half a pair is a declaration that does nothing: a threshold nobody hears, or a listener
+  // nothing ever calls. Refused rather than read as "warn nowhere".
+  if ((warnAt === undefined) !== (meter.onWarn === undefined)) {
+    throw new MeterInvalidError(name, 'warnAt', 'declared together with onWarn, or neither');
+  }
+}
+
+export function meterFact(meter: ActionMeter | undefined): ActionMeterFact | null {
+  if (meter === undefined) return null;
+  return {
+    name: meter.name,
+    period: meter.period,
+    timeZone: 'UTC',
+    limit: typeof meter.limit === 'function' ? null : meter.limit,
+    warnAt: meter.warnAt ?? null,
+  };
+}

package/src/mutator.ts

@@ -19,6 +19,7 @@ import type {
 import { action, isAction } from './action';
 import { MutatorNotIdempotentError } from './errors';
 import type { ActionHttp } from './http-path';
+import type { ActionMeter } from './meter';
 import { assertConflictClock } from './mutator-clock';
 import type { ActionPolicy } from './policy-gate';
 
@@ -93,10 +94,14 @@ export interface MutatorDef<
   readonly mcp?: ActionMcp;
   /** Same key, same meaning as an action's — a mutator IS an action. */
   readonly rateLimit?: ActionRateLimit;
+  /** Same key, same meaning as an action's: a replayed write draws nothing. */
+  readonly meter?: ActionMeter;
   /** 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;
+  /** Same key, same meaning as an action's: the refusals `server` may throw, closed. */
+  readonly errors?: readonly string[];
   /**
    * REQUIRED, and only `true`. A mutator's write is replayed under one `Idempotency-Key` —
    * `useMutation`'s retry, the offline queue's drain after a dropped response — and the server
@@ -176,8 +181,10 @@ export function mutator<
     ...(def.cache === undefined ? {} : { cache: def.cache }),
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
     ...(def.rateLimit === undefined ? {} : { rateLimit: def.rateLimit }),
+    ...(def.meter === undefined ? {} : { meter: def.meter }),
     ...(def.deprecated === undefined ? {} : { deprecated: def.deprecated }),
     ...(def.http === undefined ? {} : { http: def.http }),
+    ...(def.errors === undefined ? {} : { errors: def.errors }),
     ...(row === undefined ? {} : { row: (args: ActionRowArgs<TInput>) => row.call(def, args) }),
     idempotent: true,
     ...(def.audit === undefined ? {} : { audit: def.audit }),

package/src/openapi-complete.ts

@@ -1,9 +1,9 @@
 /**
  * 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.
+ * `servers`, the security schemes its routes are reached through, and the refusals an
+ * authenticated, limited or metered operation can answer — 401 and 429, with `Retry-After` — which
+ * the per-primitive projections cannot state: 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
@@ -11,6 +11,7 @@
  * inputs are sorted and nothing reads the clock or the environment.
  */
 
+import { toOpenApiPath } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
 import { mountedPath } from '@ultimat3/http';
 import type { ApiMount, ApiOpenApi } from './api-declaration';
@@ -62,9 +63,11 @@ function problem(description: string, headers?: Record<string, unknown>): Record
 
 const lower = (method: string): string => method.toLowerCase();
 
-/** `method path` → the route that serves it. */
+/** `method path` → the route that serves it, the path in the document's `{param}` spelling. */
 function routeIndex(routes: readonly Route[]): ReadonlyMap<string, Route> {
-  return new Map(routes.map((route) => [`${lower(route.method)} ${route.path}`, route]));
+  return new Map(
+    routes.map((route) => [`${lower(route.method)} ${toOpenApiPath(route.path)}`, route]),
+  );
 }
 
 interface Refusals {
@@ -85,12 +88,34 @@ interface Refusals {
  * still does, hence both reads above.
  */
 function declaresRateLimit(operation: Operation): boolean {
+  return declares(operation, 'rateLimit');
+}
+
+/**
+ * A `meter:` is drawn inside `invoke` too, on every surface, and refuses with `X_METER_EXCEEDED`
+ * and a `Retry-After` up to the period's end — on a public operation as on an authenticated one.
+ * Published as `x-ultimate.meter`, absent when undeclared.
+ */
+function declaresMeter(operation: Operation): boolean {
+  return declares(operation, 'meter');
+}
+
+function declares(operation: Operation, key: 'rateLimit' | 'meter'): boolean {
   const extensions = operation['x-ultimate'];
   if (typeof extensions !== 'object' || extensions === null) return false;
-  const declared = (extensions as Record<string, unknown>)['rateLimit'];
+  const declared = (extensions as Record<string, unknown>)[key];
   return declared !== undefined && declared !== null;
 }
 
+/** The codes a 429 can carry here, named so a client knows which refusal it is reading. */
+function tooManyDescription(throttled: boolean, metered: boolean): string {
+  const codes = [
+    ...(throttled ? ['X_RATE_LIMITED'] : []),
+    ...(metered ? ['X_METER_EXCEEDED'] : []),
+  ].join(' or ');
+  return `${codes} — retry after Retry-After seconds`;
+}
+
 /** 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';
@@ -98,7 +123,8 @@ function completeOperation(operation: Operation, route: Route | undefined, refus
     refusals.everyOpLimited ||
     route?.meta.rateLimitBucket !== undefined ||
     declaresRateLimit(operation);
-  if (!authenticated && !limited) return operation;
+  const metered = declaresMeter(operation);
+  if (!authenticated && !limited && !metered) return operation;
   const responses = { ...(operation['responses'] as Record<string, unknown>) };
   if (limited) {
     const ok = responses['200'] as Record<string, unknown> | undefined;
@@ -118,8 +144,9 @@ function completeOperation(operation: Operation, route: Route | undefined, refus
       refusals.unauthorizedHeaders,
     );
   }
+  // A meter is no bucket: its refusal states the delay to the period's end and no `RateLimit-*`.
   responses['429'] = problem(
-    'X_RATE_LIMITED — retry after Retry-After seconds',
+    tooManyDescription(authenticated || limited, metered),
     limited ? { ...RETRY_AFTER_HEADER, ...RATE_LIMIT_HEADERS } : RETRY_AFTER_HEADER,
   );
   return {
@@ -237,8 +264,10 @@ export function mountOpenApi(
     const scope = scopeOf.get(route.meta.name);
     if (scope === undefined) continue;
     const method = lower(route.method);
+    // The document spells a `:param` template `{param}`; the route table keeps the router's form.
+    const documented = toOpenApiPath(route.path);
     const item = (
-      Object.hasOwn(document.paths, route.path) ? document.paths[route.path] : undefined
+      Object.hasOwn(document.paths, documented) ? document.paths[documented] : undefined
     ) as Record<string, Operation> | undefined;
     const operation = item?.[method];
     if (operation === undefined) continue;
@@ -261,7 +290,7 @@ export function mountOpenApi(
     const extensions = (completed['x-ultimate'] as Record<string, unknown> | undefined) ?? {};
     for (const tag of (completed['tags'] as readonly string[] | undefined) ?? []) tags.add(tag);
     unlocks.set(scope, [...(unlocks.get(scope) ?? []), route.meta.name]);
-    const mounted = mountedPath(mount.prefix, route.path);
+    const mounted = toOpenApiPath(mountedPath(mount.prefix, route.path));
     mountedItems.set(mounted, {
       ...mountedItems.get(mounted),
       [method]: { ...completed, responses, 'x-ultimate': { ...extensions, scope } },

package/src/openapi-errors.ts

@@ -0,0 +1,18 @@
+// Single responsibility: an action operation's `responses` with its declared `errors:` in them —
+// core's builder, bound to `@ultimat3/http`'s status table and Problem `type`, and to this
+// document's `Problem` component. Undeclared, the members are today's.
+
+import { withDeclaredResponses } from '@ultimat3/core';
+import { declaredStatusFor, problemTypeFor } from '@ultimat3/http';
+import { PROBLEM_SCHEMA_NAME, schemaRef } from './naming';
+
+export function withDeclaredErrors(
+  errors: readonly string[] | undefined,
+  responses: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  return withDeclaredResponses(responses, errors, {
+    statusOf: declaredStatusFor,
+    typeFor: problemTypeFor,
+    problemRef: schemaRef(PROBLEM_SCHEMA_NAME),
+  });
+}