@ultimat3/action 29.4.0 → 30.1.0

package/src/facade.ts

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

package/src/http-path.ts

@@ -6,13 +6,25 @@
  */
 
 import type { ActionPathStyle, ActionRoute } from '@ultimat3/core';
-import { ACTION_PATH_STYLES, actionRoute } from '@ultimat3/core';
+import {
+  ACTION_PATH_STYLES,
+  actionRoute,
+  fillTemplate,
+  pathTemplateProblem,
+  renderCauseValue,
+  templateKeyProblem,
+  templateParams,
+} from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { tryIntrospect } from '@ultimat3/schema';
+import type { AnyAction } from './action';
 import {
   ActionHttpPathInvalidError,
   ActionPathDerivedEarlyError,
   ActionPathStyleInvalidError,
 } from './errors-http';
 import { defOf } from './invoke';
+import { jsonSchemaOf } from './json-schema';
 import { seatedActions } from './registry-store';
 
 /**
@@ -24,18 +36,30 @@ const pinOf = (name: string): string | undefined => {
   return seated === undefined ? undefined : defOf(seated).http?.path;
 };
 
+/** The verbs a pinned action may answer. `POST` is every unpinned action's, and the default. */
+export const ACTION_HTTP_METHODS = ['POST', 'PUT', 'PATCH', 'DELETE'] as const;
+export type ActionHttpMethod = (typeof ACTION_HTTP_METHODS)[number];
+
 /** What an action may say about its own HTTP projection. */
 export interface ActionHttp {
   /**
-   * Pin the URL, whatever the app's style derives — for a path a vendor was given and cannot be
-   * told to change (a webhook registered with a payment provider). Static and lowercase; the pin
-   * is also what a rename of the export can no longer move.
+   * Pin the URL, whatever the app's style derives — for a path a caller already holds and cannot
+   * be told to change, or a public `/v1` shaped by resource (`/orders/:id/refund`). Lowercase
+   * static segments and `:param`s, each a REQUIRED string key of `input:`: the URL's value is merged
+   * into the input before it is parsed, so the one schema validates it and the policy, the row
+   * loader and the handler read one object. The pin is also what a rename of the export can no
+   * longer move. A vendor's webhook goes to `webhookReceiver()` (`@ultimat3/jobs`) instead: an
+   * action's schema answers before any signature is checked.
    */
   readonly path?: string;
+  /** The verb the pin answers: `'POST'` (default), `'PUT'`, `'PATCH'` or `'DELETE'`. Needs `path`. */
+  readonly method?: ActionHttpMethod;
 }
 
-/** Static, lowercase, no parameters, no trailing slash. */
-const PINNED_PATH = /^(\/[a-z0-9][a-z0-9._~-]*)+$/;
+/** The method `target` is served with: its pin's, else `POST`. */
+export function methodOfHttp(http: ActionHttp | undefined): ActionHttpMethod {
+  return http?.method ?? 'POST';
+}
 
 let style: ActionPathStyle = 'resource';
 
@@ -85,26 +109,47 @@ export function resetActionPathStyle(): void {
   handedOut.clear();
 }
 
-/** Refuses a pin that is not a static lowercase path, or one under the framework's `/_x`. */
-export function assertPinnedPath(name: string, path: unknown): void {
-  if (typeof path !== 'string') {
-    throw new ActionHttpPathInvalidError({ name, path, reason: 'is not a string' });
-  }
-  if (!PINNED_PATH.test(path)) {
+/**
+ * Refuses a pin that is not a lowercase template, claims `/_x`, repeats a `:param`, or names a
+ * `:param` that is not a required string key of `input` — core's one rule, shared with
+ * `@ultimat3/query`. No `input` given proves no key, so a parameterised pin is refused then.
+ */
+export function assertPinnedPath(name: string, path: unknown, input?: unknown): void {
+  const reason =
+    pathTemplateProblem(path) ??
+    templateKeyProblem(
+      templateParams(path as string),
+      input === undefined ? undefined : tryIntrospect(input)?.properties,
+    );
+  if (reason !== undefined) throw new ActionHttpPathInvalidError({ name, path, reason });
+}
+
+/** The whole declaration: the path as above, and a method only beside a path, from the four. */
+export function assertPinnedHttp(name: string, http: ActionHttp, input: unknown): void {
+  const method: unknown = http.method;
+  if (method !== undefined && http.path === undefined) {
     throw new ActionHttpPathInvalidError({
       name,
-      path,
-      reason:
-        'is not a static lowercase path (a parameter, an uppercase letter or a trailing slash)',
+      path: http.path,
+      reason: `is absent, and http.method ${renderCauseValue(method)} has no pinned path to answer on`,
     });
   }
-  if (path === '/_x' || path.startsWith('/_x/')) {
+  if (method !== undefined && !ACTION_HTTP_METHODS.some((known) => known === method)) {
     throw new ActionHttpPathInvalidError({
       name,
-      path,
-      reason: 'claims /_x, the framework namespace',
+      path: http.path,
+      reason: `is declared with http.method ${renderCauseValue(method)}, which is not one of ${ACTION_HTTP_METHODS.join(', ')}`,
     });
   }
+  if (http.path !== undefined) assertPinnedPath(name, http.path, input);
+}
+
+/** `{ path, method }` exactly when `target` pins its URL — the manifest's fact, absent otherwise. */
+export function actionHttpPinOf(
+  target: AnyAction,
+): { readonly path: string; readonly method: ActionHttpMethod } | undefined {
+  const http = defOf(target).http;
+  return http?.path === undefined ? undefined : { path: http.path, method: methodOfHttp(http) };
 }
 
 /**
@@ -134,8 +179,45 @@ export function servedActionRoute(name: string): ActionRoute {
  * The same answer, handed to APP code by name (`derivePath`, `actionHttpPath('name')`) — which
  * may keep the string, so it is the one recorded; see `handedOut`.
  */
-export function resolveActionRoute(name: string): ActionRoute {
-  const route = servedActionRoute(name);
+export function resolveActionRoute(name: string, params?: unknown): ActionRoute {
+  const route = filledRoute(name, servedActionRoute(name), params);
   handedOut.set(name, route.path);
   return route;
 }
+
+/**
+ * A parameterised route with its `:param`s filled from `params`, each encoded as one segment. No
+ * values for a template is refused, never answered with `:id` spelled into a URL nothing serves.
+ */
+export function filledRoute(name: string, route: ActionRoute, params: unknown): ActionRoute {
+  if (templateParams(route.path).length === 0) return route;
+  const filled = fillTemplate(route.path, params);
+  if (filled.ok) return { ...route, path: filled.path };
+  throw new ActionHttpPathInvalidError({
+    name,
+    path: route.path,
+    reason: `:${filled.missing} ${filled.reason}`,
+    fix: `actionHttpPath('${name}', { ${filled.missing}: '<value>' }) — or call ${name}.client(options), which fills it from the input`,
+  });
+}
+
+/**
+ * A `:param` pin's OpenAPI parameters, `in: path` and required, in template order, each with its
+ * input member's own schema — the request body's component drops the same keys (`openapi.ts`).
+ */
+export function pathParametersOf(
+  path: string,
+  input: StandardSchemaV1,
+): readonly Record<string, unknown>[] {
+  const params = templateParams(path);
+  if (params.length === 0) return [];
+  const properties = jsonSchemaOf(input)['properties'];
+  const members: Readonly<Record<string, unknown>> =
+    typeof properties === 'object' && properties !== null ? { ...properties } : {};
+  return params.map((name) => ({
+    name,
+    in: 'path',
+    required: true,
+    schema: Object.hasOwn(members, name) ? members[name] : { type: 'string' },
+  }));
+}

package/src/http-stream.ts

@@ -0,0 +1,99 @@
+/**
+ * The HTTP projection's streamed answer: a stream-declaring action asked for with
+ * `accept: text/event-stream` answers `event: chunk` per yielded chunk, then ONE `event: done`
+ * (the output) or `event: error` (the problem document), then closes. A refusal decided before the
+ * handler starts — the policy, the input, the rate limit — is the ordinary problem response.
+ */
+
+import { useContext, withChildContext } from '@ultimat3/core';
+import { toProblem } from '@ultimat3/http';
+import type { ChunkSink } from './action-stream';
+
+export const EVENT_STREAM = 'text/event-stream';
+
+/** A comment line every interval, so an idle proxy does not close a long answer. */
+export const HEARTBEAT_MS = 15_000;
+
+/** True for a request that lists `text/event-stream` in its `accept`. */
+export function wantsEventStream(accept: string | null): boolean {
+  if (accept === null) return false;
+  return accept
+    .split(',')
+    .some((part) => part.split(';')[0]?.trim().toLowerCase() === EVENT_STREAM);
+}
+
+const encoder = new TextEncoder();
+const STARTED: unique symbol = Symbol('started');
+
+/** One SSE frame. JSON never holds a raw newline, so `data:` is always one line. */
+export function sseFrame(event: 'chunk' | 'done' | 'error', data: unknown): Uint8Array {
+  return encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data ?? null)}\n\n`);
+}
+
+/** Runs the invocation with `sink` receiving its chunks; resolves the output. */
+export type StreamRun = (sink: ChunkSink) => Promise<unknown>;
+
+/**
+ * Starts `run` and answers once the handler has started (the stream) or the invocation settled
+ * first (a refusal is THROWN, so the route's error path answers it; a replay is a lone `done`).
+ */
+export async function streamAnswer(
+  owner: object,
+  run: StreamRun,
+  heartbeatMs: number = HEARTBEAT_MS,
+): Promise<Response> {
+  const requestId = useContext().requestId;
+  // The client leaving cancels the body; that aborts this signal, added to the request's own.
+  const left = new AbortController();
+  let out: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let closed = false;
+  const send = (bytes: Uint8Array): void => {
+    if (!closed) out?.enqueue(bytes);
+  };
+  let begin: () => void = () => undefined;
+  const started = new Promise<typeof STARTED>((resolve) => {
+    begin = () => resolve(STARTED);
+  });
+  const sink: ChunkSink = {
+    owner,
+    start: () => begin(),
+    push: (chunk) => send(sseFrame('chunk', chunk)),
+  };
+  const settled = withChildContext({ signal: left.signal }, () => run(sink));
+  // Settled without starting is a refusal — thrown here, before any byte — or a replayed answer,
+  // which streams as a lone `done`.
+  await Promise.race([started, settled]);
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      out = controller;
+      timer = setInterval(() => send(encoder.encode(': keep-alive\n\n')), heartbeatMs);
+      const finish = (bytes: Uint8Array): void => {
+        clearInterval(timer);
+        send(bytes);
+        if (!closed) {
+          closed = true;
+          controller.close();
+        }
+      };
+      settled.then(
+        (output) => finish(sseFrame('done', output)),
+        (error: unknown) => finish(sseFrame('error', toProblem(error, { requestId }))),
+      );
+    },
+    cancel() {
+      closed = true;
+      clearInterval(timer);
+      left.abort();
+    },
+  });
+  return new Response(body, {
+    status: 200,
+    headers: {
+      'content-type': `${EVENT_STREAM}; charset=utf-8`,
+      'cache-control': 'no-store',
+      // nginx and its kin buffer a response unless told not to; a buffered stream is a JSON answer.
+      'x-accel-buffering': 'no',
+    },
+  });
+}

package/src/http.ts

@@ -10,24 +10,29 @@ import type { Deprecation } from '@ultimat3/core';
 import {
   IDEMPOTENCY_HEADER,
   isMcpExposed,
+  mergePathParams,
   RECORDS_OPENAPI_HEADER,
+  REPLAYED_HEADER,
   recordDeprecatedCall,
   recordEnvelopeSchema,
   renderDeprecation,
+  templateParams,
   useContext,
   withWriteOrigin,
   writeDigest,
 } from '@ultimat3/core';
 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 { jsonResponse, publishRateLimit, redirect, takeRedirect, toBucket } from '@ultimat3/http';
+import { jsonResponse, publishRateLimit, redirect, takeRedirect } from '@ultimat3/http';
 import { admitsAnonymous, policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { ActionRateLimit, AnyAction } from './action';
+import { withChunkSink } from './action-stream';
 import { ActionDeprecationInvalidError } from './errors';
-import { actionPathStyle, servedActionRoute } from './http-path';
+import { ActionDeprecationSuccessorInvalidError } from './errors-http';
+import { actionPathStyle, methodOfHttp, pathParametersOf, servedActionRoute } from './http-path';
+import { EVENT_STREAM, streamAnswer, wantsEventStream } from './http-stream';
 import { actionName, defOf, invoke } from './invoke';
+import type { ActionMeter } from './meter';
+import { meterFact } from './meter';
 import {
   inputSchemaName,
   outputSchemaName,
@@ -35,10 +40,10 @@ import {
   schemaRef,
   toOperationId,
 } from './naming';
+import { withDeclaredErrors } from './openapi-errors';
+import { assertActionRateLimit, fixedRateLimit } from './rate-limit-gate';
 import { carriesRecords, recordResponse } from './record-wire';
 
-export const REPLAYED_HEADER = 'x-ultimate-replayed';
-
 /** The digest a request's idempotency key names its write by; none for a missing or blank one. */
 async function writeOriginOf(req: UltimateRequest): Promise<string | undefined> {
   const key = req.header(IDEMPOTENCY_HEADER);
@@ -55,9 +60,18 @@ export function toRoute(target: AnyAction): Route {
   // name still has the path it declared. Reading only the seated registry answered the style's
   // derived path for an unseated pinned action — right by coincidence under `resource`, wrong
   // under `readable` (a shared test worker whose app declared it, 22.7).
-  const pinned = defOf(target).http?.path;
-  const path = pinned ?? servedActionRoute(actionName(target)).path;
-  return projectRoute(target, path, (req) => req.bodyRaw());
+  const http = defOf(target).http;
+  const path = http?.path ?? servedActionRoute(actionName(target)).path;
+  const owner = `action "${actionName(target)}"`;
+  // A `:param` pin's values come from the router's DECODED params and join the body before
+  // `invoke` parses it: one input for the schema, the policy, the row loader and the handler. A
+  // body naming the same key differently is refused (`X_HTTP_PATH_INPUT_CONFLICT`), never overridden.
+  const readInput =
+    templateParams(path).length === 0
+      ? (req: UltimateRequest) => req.bodyRaw()
+      : async (req: UltimateRequest) =>
+          mergePathParams({ owner, template: path, params: req.params, raw: await req.bodyRaw() });
+  return projectRoute(target, path, readInput, methodOfHttp(http));
 }
 
 /**
@@ -68,17 +82,23 @@ export function toRoute(target: AnyAction): Route {
  * `toRoute`'s: the policy, the idempotency, the redirect a handler asks for, the problem document.
  */
 export function toPostBinding(target: AnyAction, path: string): Route {
-  return projectRoute(target, path, async (req) => {
-    const body = await req.bodyRaw();
-    const fields = typeof body === 'object' && body !== null && !Array.isArray(body) ? body : {};
-    return { ...fields, ...req.queryRaw() };
-  });
+  return projectRoute(
+    target,
+    path,
+    async (req) => {
+      const body = await req.bodyRaw();
+      const fields = typeof body === 'object' && body !== null && !Array.isArray(body) ? body : {};
+      return { ...fields, ...req.queryRaw() };
+    },
+    'POST',
+  );
 }
 
 function projectRoute(
   target: AnyAction,
   path: string,
   readInput: (req: UltimateRequest) => Promise<unknown>,
+  method: Route['method'],
 ): Route {
   const name = actionName(target);
   const def = defOf(target);
@@ -87,8 +107,9 @@ function projectRoute(
   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);
+  if (def.rateLimit !== undefined) assertActionRateLimit(name, def.rateLimit);
   const enveloped = carriesRecords(target.output);
+  const streams = def.stream !== undefined;
 
   const handler = async (req: UltimateRequest): Promise<Response> => {
     if (sunsetting !== undefined) {
@@ -112,18 +133,25 @@ function projectRoute(
     // The header NAMES the write whatever the declaration, idempotent or not: a page sends one
     // with every mutation, and the `records` frames its rows produce carry the digest so that
     // page can tell its own echo from somebody else's change (`@ultimat3/core`'s write origin).
-    const result = await withWriteOrigin(await writeOriginOf(req), () =>
-      invoke(target, raw, {
-        surface: 'http',
-        idempotencyKey: key,
-        onReplay: () => {
-          replayed = true;
-        },
-        clientAddress: req.ctx.ip,
-        onRateLimit: (decision) =>
-          publishRateLimit(req.ctx, decision, useContext().now().getTime()),
-      }),
-    );
+    const origin = await writeOriginOf(req);
+    const call = (): Promise<unknown> =>
+      withWriteOrigin(origin, () =>
+        invoke(target, raw, {
+          surface: 'http',
+          idempotencyKey: key,
+          onReplay: () => {
+            replayed = true;
+          },
+          clientAddress: req.ctx.ip,
+          onRateLimit: (decision) =>
+            publishRateLimit(req.ctx, decision, useContext().now().getTime()),
+        }),
+      );
+    // The same invocation, its chunks sent as they are yielded: one route, chosen by `accept`.
+    if (streams && wantsEventStream(req.header('accept'))) {
+      return streamAnswer(def, (sink) => withChunkSink(sink, call));
+    }
+    const result = await call();
     // The one thing an action's return value cannot say. `setRedirect()` inside the handler
     // is how a `<form method="post">` gets an answer a browser follows — a `Location` on the
     // 200 this used to always return is a header browsers ignore, so a JS-less form left the
@@ -165,7 +193,7 @@ function projectRoute(
     // called over MCP, over the typed client or directly answered `X_INPUT_INVALID`. One action,
     // one input schema, two codes, decided by the surface the call arrived through.
     //
-    // `invoke`'s own `validateInput` is the one parser now, and nothing is lost by dropping this:
+    // `invoke`'s own `parseActionInput` is the one parser now, and nothing is lost by dropping this:
     // `bodyRaw()` still parses by content-type, caches, and enforces the size cap — the body stage
     // only ever added SCHEMA validation on top. `X_BODY_INVALID` keeps its job, which is a body
     // failing a plain `route.ts`'s own schema, where no primitive owns the input.
@@ -179,7 +207,7 @@ function projectRoute(
     ...(def.mcp?.description === undefined ? {} : { description: def.mcp.description }),
   };
 
-  return { method: 'POST', path, handler, meta };
+  return { method, path, handler, meta };
 }
 
 /**
@@ -219,17 +247,20 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
   const deprecation = deprecationMetaFor(name, def.deprecated);
   const outputRef = schemaRef(outputSchemaName(name));
   const enveloped = carriesRecords(target.output);
+  // A `:param` pin's values are path parameters; an unpinned operation's bytes are unchanged.
+  const inPath = pathParametersOf(def.http?.path ?? '', target.input);
   return {
     operationId: toOperationId(name),
     tags: [operationTagOf(target)],
     summary: def.mcp?.description ?? name,
     ...(deprecation === undefined ? {} : { deprecated: true }),
-    parameters: idempotent ? [IDEMPOTENCY_PARAMETER] : [],
+    parameters: [...inPath, ...(idempotent ? [IDEMPOTENCY_PARAMETER] : [])],
     requestBody: {
       required: true,
       content: { 'application/json': { schema: { $ref: schemaRef(inputSchemaName(name)) } } },
     },
-    responses: {
+    // The declared refusals join the framework's own, per status (`openapi-errors.ts`).
+    responses: withDeclaredErrors(def.errors, {
       // Only an output that references an entity row changes shape: every other operation's
       // bytes are the ones `x verify`'s contract diff already holds.
       '200': enveloped
@@ -238,7 +269,14 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
             headers: RECORDS_OPENAPI_HEADER,
             content: { 'application/json': { schema: recordEnvelopeSchema({ $ref: outputRef }) } },
           }
-        : { description: 'ok', content: { 'application/json': { schema: { $ref: outputRef } } } },
+        : {
+            description: 'ok',
+            content: {
+              'application/json': { schema: { $ref: outputRef } },
+              // A stream-declaring action answers the same route as SSE when asked for it.
+              ...(def.stream === undefined ? {} : { [EVENT_STREAM]: STREAM_CONTENT }),
+            },
+          },
       // BOTH, because they are two different failures and this operation published only one of
       // them while the route answered only the other. `X_INPUT_INVALID` is the body that parsed
       // and failed THIS action's declared schema — the primitive's own code, identical over MCP,
@@ -246,11 +284,13 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
       // at all: malformed JSON, over `bodyLimitBytes`, an unreadable content type. That one is
       // HTTP-only, because only HTTP has bytes, and it is raised in `bodyRaw()` before any schema
       // exists to fail.
-      '400': problemResponse('X_INPUT_INVALID'),
+      '400': problemResponse(
+        inPath.length === 0 ? 'X_INPUT_INVALID' : 'X_INPUT_INVALID or X_HTTP_PATH_INPUT_CONFLICT',
+      ),
       '422': problemResponse('X_BODY_INVALID'),
       '403': problemResponse('policy denied'),
       ...(idempotent ? { '409': problemResponse('X_IDEMPOTENCY_CONFLICT') } : {}),
-    },
+    }),
     'x-ultimate': {
       capability: policyCapability(def.policy),
       idempotent,
@@ -263,6 +303,8 @@ export function toOpenApiOperation(target: AnyAction): OpenApiOperation {
       // exist. Verbatim, and never derived — this is a published contract, not a label.
       mcpTool: isMcpExposed(def.mcp) ? name : null,
       rateLimit: rateLimitMeta(name, def.rateLimit),
+      // Absent, not null, when undeclared: an action without a meter keeps `openapi.json`'s bytes.
+      ...(def.meter === undefined ? {} : { meter: meterMeta(def.meter) }),
       // The dates as data, beside the boolean flag OpenAPI defines: `deprecated: true` says an
       // operation is going away and nothing else, so a client that wants to plan the migration
       // has to read the sunset out of prose. Absent, not null, for the same byte-stability
@@ -283,6 +325,15 @@ function deprecationHeadersFor(
   if (deprecated === undefined) return undefined;
   const successor =
     deprecated.replacedBy === undefined ? undefined : servedActionRoute(deprecated.replacedBy).path;
+  if (deprecated.replacedBy !== undefined && successor !== undefined) {
+    if (templateParams(successor).length > 0) {
+      throw new ActionDeprecationSuccessorInvalidError({
+        name,
+        successor: deprecated.replacedBy,
+        path: successor,
+      });
+    }
+  }
   const rendered = renderDeprecation(deprecated, successor);
   if (!rendered.ok) throw new ActionDeprecationInvalidError(name, rendered.field, rendered.value);
   return rendered.headers;
@@ -302,14 +353,31 @@ function deprecationMetaFor(
 function rateLimitMeta(
   name: string,
   limit: ActionRateLimit | undefined,
-): Record<string, number> | null {
+): Record<string, number | string> | null {
   if (limit === undefined) return null;
   // Validated through the same call the route makes, so the spec cannot publish a pair the
   // limiter would have refused to run on.
-  toBucket(name, limit);
-  return { limit: limit.limit, windowMs: limit.windowMs };
+  assertActionRateLimit(name, limit);
+  // A limit resolved per call has no number to publish; saying so keeps the 429 documented.
+  return fixedRateLimit(limit) ?? { limit: 'per-call', windowMs: limit.windowMs };
 }
 
+/** The meter as spec data: the period and its zone, and the limit when it is a fixed number. */
+function meterMeta(meter: ActionMeter): Record<string, number | string> {
+  const fact = meterFact(meter);
+  return {
+    name: meter.name,
+    period: meter.period,
+    timeZone: 'UTC',
+    limit: fact?.limit ?? 'per-call',
+  };
+}
+
+/** `accept: text/event-stream`: `chunk` frames, then one `done` (the output) or `error` (a problem). */
+const STREAM_CONTENT: Record<string, unknown> = {
+  schema: { type: 'string', description: 'event: chunk | done | error; data: one JSON value' },
+};
+
 const IDEMPOTENCY_PARAMETER: Record<string, unknown> = {
   name: 'Idempotency-Key',
   in: 'header',