@ultimat3/action 29.4.0 → 30.1.0

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@ultimat3/action",
-  "version": "29.4.0",
+  "version": "30.1.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "action",
+    "rpc",
+    "openapi",
+    "mcp",
+    "typed-client"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Actions",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -35,12 +46,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "29.4.0",
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/db": "29.4.0",
-    "@ultimat3/entity": "29.4.0",
-    "@ultimat3/http": "29.4.0",
-    "@ultimat3/policy": "29.4.0",
-    "@ultimat3/schema": "29.4.0"
+    "@ultimat3/cache": "30.1.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/db": "30.1.0",
+    "@ultimat3/entity": "30.1.0",
+    "@ultimat3/http": "30.1.0",
+    "@ultimat3/policy": "30.1.0",
+    "@ultimat3/schema": "30.1.0"
   }
 }

package/src/action-stream.ts

@@ -0,0 +1,116 @@
+/**
+ * A stream-declaring action's handler, drained. `handle` is an async generator: every yielded chunk
+ * is parsed by `stream`, handed to the sink the HTTP stream projection opened (if any), and the
+ * generator's RETURN value is the output — so `invoke`, MCP, `.job()` and `.as()` keep one contract.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { asyncContext } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { formatIssues, validateAsync } from '@ultimat3/schema';
+import { ActionStreamInvalidError } from './errors-stream';
+
+/** Where a draining handler hands its chunks: `http-stream.ts` opens one per streamed request. */
+export interface ChunkSink {
+  /** The wrapped declaration this sink is for — a nested action's chunks never reach it. */
+  readonly owner: object;
+  /** Called once, when the handler starts: the policy has passed by then. */
+  start(): void;
+  push(chunk: unknown): void | Promise<void>;
+}
+
+const sinks = asyncContext<{ readonly sink: ChunkSink; claimed: boolean }>('an action stream');
+/** Whether the handler being drained right now has a reader for its chunks. */
+const reading = asyncContext<boolean>('an action stream reader');
+
+/**
+ * Inside a stream-declaring `handle`: `true` when a caller is reading the chunks as they are
+ * yielded (a `text/event-stream` request), `false` when the call is drained to its output alone
+ * (MCP, `.job()`, `.as()`, JSON). A handler whose chunks cost something — `llm()` gives up its
+ * repair turn to stream — produces them only when they are read. Per declaration: a nested
+ * action's handler reads `false` unless it is the one the stream was opened for.
+ */
+export function chunksRead(): boolean {
+  return reading.get() === true;
+}
+
+/** Run `fn` with `sink` receiving the chunks of the first draining handler that `owner` names. */
+export function withChunkSink<T>(sink: ChunkSink, fn: () => T): T {
+  return sinks.run({ sink, claimed: false }, fn);
+}
+
+interface StreamingDef {
+  readonly stream?: StandardSchemaV1;
+  handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
+}
+
+/**
+ * The declaration `invoke` runs: `def` unchanged without `stream`, else a copy whose `handle`
+ * drains. Built per name, so an error names the action that was called.
+ */
+export function streamingDef<D extends StreamingDef>(def: D, name: () => string): D {
+  const stream = def.stream;
+  if (stream === undefined) return def;
+  const wrapped: D = {
+    ...def,
+    handle: (args: { readonly input: unknown; readonly ctx: Ctx }) =>
+      drain(wrapped, stream, name(), def.handle(args)),
+  };
+  return wrapped;
+}
+
+function isAsyncGenerator(value: unknown): value is AsyncGenerator<unknown, unknown, undefined> {
+  if (typeof value !== 'object' || value === null) return false;
+  const candidate = value as { readonly next?: unknown; readonly [Symbol.asyncIterator]?: unknown };
+  return (
+    typeof candidate.next === 'function' && typeof candidate[Symbol.asyncIterator] === 'function'
+  );
+}
+
+async function drain(
+  owner: object,
+  stream: StandardSchemaV1,
+  name: string,
+  produced: unknown,
+): Promise<unknown> {
+  if (!isAsyncGenerator(produced)) {
+    throw new ActionStreamInvalidError(
+      name,
+      'its handle is not an async generator (async *handle)',
+    );
+  }
+  const open = sinks.get();
+  // Claimed once: the first draining handler of THIS declaration owns the response stream.
+  const sink = open !== undefined && !open.claimed && open.sink.owner === owner ? open.sink : null;
+  if (open !== undefined && sink !== null) open.claimed = true;
+  sink?.start();
+  // Every resume of the generator runs inside this scope, so its body reads `chunksRead()`.
+  return reading.run(sink !== null, () => pump(produced, stream, name, sink));
+}
+
+async function pump(
+  produced: AsyncGenerator<unknown, unknown, undefined>,
+  stream: StandardSchemaV1,
+  name: string,
+  sink: ChunkSink | null,
+): Promise<unknown> {
+  try {
+    for (;;) {
+      const step = await produced.next();
+      if (step.done === true) return step.value;
+      const parsed = await validateAsync(stream, step.value);
+      if (parsed.issues !== undefined) {
+        const issues = formatIssues(parsed.issues).join('; ');
+        throw new ActionStreamInvalidError(
+          name,
+          `yielded a chunk its stream schema refuses: ${issues}`,
+        );
+      }
+      await sink?.push(parsed.value);
+    }
+  } finally {
+    // A throw above (a refused chunk, a sink that failed) ends the generator, so its own
+    // `finally` runs and nothing it holds is left open.
+    await produced.return(undefined);
+  }
+}

package/src/action.ts

@@ -8,22 +8,27 @@
 import type { CacheTag } from '@ultimat3/cache';
 import { tagKeys } from '@ultimat3/cache';
 import type { Actor, Ctx, Deprecation, McpExposureDeclaration } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
+import { checkDeclaredErrors, isMcpExposed } from '@ultimat3/core';
 import type { RateLimitDecision } from '@ultimat3/http';
+import { declaredStatusFor } from '@ultimat3/http';
 import { policyCapability, policyPermissions } from '@ultimat3/policy';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import type { ClientMethod, ClientOptions } from './client';
+import { streamingDef } from './action-stream';
+import type { ClientMethod, ClientOptions, StreamClientMethod } from './client';
 import type { ContractTest, ContractTestOptions } from './contract-test';
 import { facadeFor } from './facade';
 import type { OpenApiOperation } from './http';
-import type { ActionHttp } from './http-path';
-import { routeFor } from './http-path';
+import type { ActionHttp, ActionHttpMethod } from './http-path';
+import { methodOfHttp, routeFor } from './http-path';
 import type { IdempotencyStore } from './idempotency';
 import { actionName, defOf, hasDef, invoke, stashDef } from './invoke';
 import type { ActionJobHandle } from './job-handle';
 import type { JsonSchemaObject } from './json-schema';
 import { jsonSchemaOf } from './json-schema';
+import type { ActionMeter, ActionMeterFact, ResolvedLimit } from './meter';
+import { assertMeterDeclaration, meterFact } from './meter';
 import type { ActionPolicy, Surface } from './policy-gate';
+import { fixedRateLimit } from './rate-limit-gate';
 
 export interface ActionCache {
   /** Tags dropped from every cache tier after the handler settles. */
@@ -37,6 +42,13 @@ export interface ActionCache {
 export type ActionMcp = Omit<McpExposureDeclaration, 'listParams'>;
 
 export interface ActionRateLimit {
+  /** The burst, or one resolved per call from `ctx` (`({ ctx }) => planOf(ctx).perMinute`). */
+  readonly limit: ResolvedLimit;
+  readonly windowMs: number;
+}
+
+/** A rate limit as data: the fixed pair a contract can diff. */
+export interface ActionRateLimitFact {
   readonly limit: number;
   readonly windowMs: number;
 }
@@ -63,10 +75,18 @@ export interface ActionDef<
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly rateLimit?: ActionRateLimit;
+  /**
+   * A durable per-period allowance, drawn once per call on EVERY surface — HTTP, MCP, a job, an
+   * in-process call — after the policy admits it and before `handle` starts. Spent, the call is
+   * `X_METER_EXCEEDED`. A replayed idempotent call draws nothing. Periods are UTC (`meter.ts`).
+   */
+  readonly meter?: ActionMeter;
   /**
    * The HTTP projection's one per-action knob: `http: { path }` pins the URL whatever the app's
-   * `pathStyle` derives — for a webhook a vendor was given. Everything else about the route (the
-   * method, the policy, the body) stays the framework's.
+   * `pathStyle` derives — for a path a caller holds and cannot be told to change (a signed upload).
+   * Everything else about the route (the method, the policy, the body) stays the framework's. An
+   * inbound WEBHOOK is not this door: it is `webhookReceiver()` from `@ultimat3/jobs`, whose route
+   * verifies the vendor's bytes before anything parses them.
    */
   readonly http?: ActionHttp;
   /**
@@ -84,6 +104,14 @@ export interface ActionDef<
   readonly deprecated?: Deprecation;
   /** Marks the action safe to retry with an `Idempotency-Key`. */
   readonly idempotent?: boolean;
+  /**
+   * The refusals a caller may branch on: each a registered 4xx code (`defineError` first), listed
+   * once — else `X_ACTION_ERRORS_INVALID` here. Declared, the list is CLOSED: a 4xx code thrown out
+   * of `handle` or `row` that it does not name is `X_ERROR_UNDECLARED` in a test or dev run
+   * (production answers it unchanged, warns and counts), and `.contract()` scans the handler's own
+   * source for one. The OpenAPI operation and the MCP tool publish it. Absent: today's open contract.
+   */
+  readonly errors?: readonly string[];
   /**
    * Record every attempt at this action through the installed `AuditSink` — allowed, denied and
    * failed alike. Opt-in per declaration and never a global switch: a login and a price change
@@ -111,6 +139,24 @@ export interface ActionDef<
   handle(args: ActionHandlerArgs<TInput>): Promise<InferOutput<TOutput>> | InferOutput<TOutput>;
 }
 
+/**
+ * An action that answers in pieces before it answers: `stream` is the schema every yielded chunk
+ * is parsed by, and `handle` an async generator whose RETURN value is the output. An ordinary call
+ * (MCP, `.job()`, `.as()`, a JSON request) drains it and answers the output alone; a request with
+ * `accept: text/event-stream` is sent each chunk as it is yielded (`http-stream.ts`).
+ */
+export interface StreamActionDef<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TChunk extends StandardSchemaV1,
+  TRow = unknown,
+> extends Omit<ActionDef<TInput, TOutput, TRow>, 'handle'> {
+  readonly stream: TChunk;
+  handle(
+    args: ActionHandlerArgs<TInput>,
+  ): AsyncGenerator<InferInput<TChunk>, InferOutput<TOutput>, undefined>;
+}
+
 export interface InvokeOptions {
   /** Explicit context. Omitted means "take the ambient request context". */
   readonly ctx?: Ctx;
@@ -156,7 +202,8 @@ export interface ActionDescriptor {
   readonly name: string;
   readonly verb: string;
   readonly resource: string;
-  readonly method: 'POST';
+  /** The verb the route answers: `http.method` on a pin, `POST` otherwise (`methodOfHttp`). */
+  readonly method: ActionHttpMethod;
   readonly path: string;
   /** The policy's DISPLAY label. A composite renders as `and(a:b, c:d)` — never a permission. */
   readonly capability: string;
@@ -177,9 +224,15 @@ export interface ActionDescriptor {
    */
   readonly audited: boolean;
   readonly mcp: McpDescriptorMeta;
-  readonly rateLimit: ActionRateLimit | null;
+  /** The FIXED pair; `null` when none is declared or the limit is resolved per call. */
+  readonly rateLimit: ActionRateLimitFact | null;
+  /** The window of a rate limit resolved per call, which has no static number to publish. */
+  readonly rateLimitPerCall: { readonly windowMs: number } | null;
+  readonly meter: ActionMeterFact | null;
   /** Published so `x actions list --json` can answer "what is retiring, and when". */
   readonly deprecated: Deprecation | null;
+  /** The declared refusals, sorted; `null` for an action that declares none (an open contract). */
+  readonly errors: readonly string[] | null;
 }
 
 /**
@@ -194,10 +247,13 @@ export interface AnyActionDef {
   readonly cache?: ActionCache;
   readonly mcp?: ActionMcp;
   readonly rateLimit?: ActionRateLimit;
+  readonly meter?: ActionMeter;
   readonly http?: ActionHttp;
   readonly deprecated?: Deprecation;
   readonly idempotent?: boolean;
+  readonly errors?: readonly string[];
   readonly audit?: boolean;
+  readonly stream?: StandardSchemaV1;
   row?(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
   handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
 }
@@ -210,6 +266,8 @@ export interface AnyAction {
   readonly output: StandardSchemaV1;
   readonly policy: ActionPolicy;
   readonly mcp?: ActionMcp;
+  /** The declared refusals, checked and sorted; absent for an open contract. */
+  readonly errors?: readonly string[];
   describe(): ActionDescriptor;
   /** A twin under another name. Registration uses `nameAction`, which names in place. */
   named(name: string): AnyAction;
@@ -255,18 +313,47 @@ export interface Action<
   job(): ActionJobHandle<TInput, TOutput>;
 }
 
+/**
+ * An action that declared `stream`: the same action, whose typed client also carries
+ * `.stream(input)` yielding `TChunk`. The chunk schema is not lifted onto the action — `llm()`'s
+ * server-side `.stream()` method owns that member name — so `TChunk` lives in `client()`'s type.
+ */
+export interface StreamAction<
+  TInput extends StandardSchemaV1 = StandardSchemaV1,
+  TOutput extends StandardSchemaV1 = StandardSchemaV1,
+  TChunk extends StandardSchemaV1 = StandardSchemaV1,
+> extends Action<TInput, TOutput> {
+  named(name: string): StreamAction<TInput, TOutput, TChunk>;
+  client(options: ClientOptions): StreamClientMethod<TInput, TOutput, TChunk>;
+}
+
 /** The fluent half of an action: lifted declaration plus one method per projection. */
 export type ActionFacade<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1> = Pick<
   Action<TInput, TOutput>,
   'input' | 'output' | 'policy' | 'mcp' | 'as' | 'openapi' | 'client' | 'job' | 'contract'
 >;
 
+export function action<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TChunk extends StandardSchemaV1 = StandardSchemaV1,
+  TRow = unknown,
+>(def: StreamActionDef<TInput, TOutput, TChunk, TRow>): StreamAction<TInput, TOutput, TChunk>;
+export function action<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TRow = unknown,
+>(def: ActionDef<TInput, TOutput, TRow>): Action<TInput, TOutput>;
 export function action<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
   TRow = unknown,
 >(def: ActionDef<TInput, TOutput, TRow>): Action<TInput, TOutput> {
-  return build(def, '');
+  // Refused where it is written, and frozen before `build` stores it: the list a caller still
+  // holds is not the one the descriptor, the document and the wrap read.
+  const errors = checkDeclaredErrors(def.errors, declaredStatusFor, 'this action');
+  if (def.meter !== undefined) assertMeterDeclaration(def.meter);
+  return build(errors === undefined ? def : { ...def, errors }, '');
 }
 
 /**
@@ -293,6 +380,11 @@ export function nameAction<A extends AnyAction>(target: A, name: string): A {
   return target;
 }
 
+/** The one member a stream-declaring definition adds, read through the erased `ActionDef`. */
+interface StreamFields {
+  readonly stream?: StandardSchemaV1;
+}
+
 function build<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1, TRow>(
   def: ActionDef<TInput, TOutput, TRow>,
   name: string,
@@ -309,11 +401,16 @@ function build<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1
     describe: (): ActionDescriptor => describeAction(self),
     named: (next: string): Action<TInput, TOutput> => build(def, next),
     ...facadeFor(def, () => self),
+    ...(def.errors === undefined ? {} : { errors: def.errors }),
   });
   // `name` on a function is non-writable, so Object.assign cannot set it.
   Object.defineProperty(self, 'name', { value: name, configurable: true });
-  // The declaration goes to `invoke.ts` and stays there: `handle` has no other reader.
-  stashDef(self, def);
+  // The declaration goes to `invoke.ts` and stays there: `handle` has no other reader. A
+  // stream-declaring one is stored draining (`action-stream.ts`), so `invoke` stays one path.
+  stashDef(
+    self,
+    streamingDef(def as ActionDef<TInput, TOutput, TRow> & StreamFields, () => name),
+  );
   return self;
 }
 
@@ -331,7 +428,7 @@ export function describeAction(target: AnyAction): ActionDescriptor {
     name,
     verb: path.verb,
     resource: path.resource,
-    method: 'POST',
+    method: methodOfHttp(def.http),
     path: path.path,
     capability: policyCapability(def.policy),
     // The flattened list, beside the label and never instead of it: one is read, one is matched.
@@ -354,7 +451,13 @@ export function describeAction(target: AnyAction): ActionDescriptor {
       tool: name,
       description: mcp?.description ?? null,
     },
-    rateLimit: def.rateLimit ?? null,
+    rateLimit: fixedRateLimit(def.rateLimit),
+    rateLimitPerCall:
+      def.rateLimit !== undefined && typeof def.rateLimit.limit === 'function'
+        ? { windowMs: def.rateLimit.windowMs }
+        : null,
+    meter: meterFact(def.meter),
     deprecated: def.deprecated ?? null,
+    errors: def.errors ?? null,
   };
 }

package/src/audit-subject-target.ts

@@ -0,0 +1,81 @@
+// `auditSubjectTarget()`: `x_audit` as a subject target a `defineSubject({ targets })` lists —
+// structural, so `@ultimat3/jobs` (this tier) imports nothing from here. The erase never deletes a
+// trail row: it overwrites who acted (`actor_id`, `on_behalf_of_id`) and the input they sent, so
+// the record of WHAT happened stays. An app that must keep the person too lists it `{ retain }`.
+
+import type { PgExecutor } from '@ultimat3/core';
+
+/** The subject as a target is handed it: the key asked for, and the subject's row read fresh. */
+export interface AuditSubjectRef {
+  readonly key: string;
+  readonly row: Readonly<Record<string, unknown>>;
+}
+
+export interface AuditSubjectTargetOptions {
+  readonly executor: PgExecutor;
+  /** The `actor_id` the subject acted as. Default: the subject's key. `undefined` touches nothing. */
+  readonly actor?: (subject: AuditSubjectRef) => string | undefined;
+  /** What replaces the actor. Default `'erased'`: a fixed word, never derived from the person. */
+  readonly placeholder?: string;
+}
+
+type Cell = string | number | boolean | null;
+
+export interface AuditSubjectTarget {
+  readonly name: 'x_audit';
+  readonly columns: readonly string[];
+  exportPage(
+    subject: AuditSubjectRef,
+    cursor: string | null,
+    size: number,
+  ): Promise<{
+    readonly rows: readonly Readonly<Record<string, Cell>>[];
+    readonly cursor: string | null;
+  }>;
+  erase(subject: AuditSubjectRef, size: number): Promise<number>;
+}
+
+export const AUDIT_SUBJECT_COLUMNS = [
+  'id',
+  'at',
+  'action',
+  'primitive',
+  'surface',
+  'outcome',
+  'org_id',
+] as const;
+
+// Keyset on the uuid v7 id, which is time-ordered: a page resumes where the last one ended.
+const SQL_PAGE = `select id::text as id, at::text as at, action, primitive, surface, outcome, org_id
+  from x_audit where (actor_id = $1 or on_behalf_of_id = $1)
+  and ($2::uuid is null or id > $2::uuid) order by id limit $3`;
+
+// Bounded: one statement rewrites at most `size` rows, and a replay finds none left to rewrite.
+const SQL_ERASE = `update x_audit set
+  actor_id = case when actor_id = $1 then $2 else actor_id end,
+  on_behalf_of_id = case when on_behalf_of_id = $1 then $2 else on_behalf_of_id end,
+  input = null
+  where id in (select id from x_audit where actor_id = $1 or on_behalf_of_id = $1 limit $3)
+  returning id`;
+
+export function auditSubjectTarget(options: AuditSubjectTargetOptions): AuditSubjectTarget {
+  const { executor } = options;
+  const actorOf = options.actor ?? ((subject: AuditSubjectRef) => subject.key);
+  const placeholder = options.placeholder ?? 'erased';
+  return {
+    name: 'x_audit',
+    columns: AUDIT_SUBJECT_COLUMNS,
+    async exportPage(subject, cursor, size) {
+      const actor = actorOf(subject);
+      if (actor === undefined) return { rows: [], cursor: null };
+      const rows = await executor.query<Record<string, Cell>>(SQL_PAGE, [actor, cursor, size]);
+      const last = rows.at(-1)?.['id'];
+      return { rows, cursor: rows.length < size || typeof last !== 'string' ? null : last };
+    },
+    async erase(subject, size) {
+      const actor = actorOf(subject);
+      if (actor === undefined) return 0;
+      return (await executor.query(SQL_ERASE, [actor, placeholder, size])).length;
+    },
+  };
+}

package/src/client.ts

@@ -25,15 +25,20 @@ import type {
 import {
   actionPath,
   BUILD_ID_HEADER,
+  clientStream,
   clientTransport,
   FRAMEWORK_CODE,
+  fillWire,
   isJsonObject,
   problemOf,
   remoteTitleOf,
+  renderedActionPin,
 } from '@ultimat3/core';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import type { Action } from './action';
+import type { Action, StreamAction } from './action';
 import { ContractDriftError, RemoteActionError } from './errors';
+import { ActionHttpPathInvalidError } from './errors-http';
+import type { ActionHttp } from './http-path';
 import { issuesFromWire } from './wire-issues';
 
 /**
@@ -58,11 +63,20 @@ export interface CallOptions {
   readonly retry?: ClientRetry;
 }
 
-/** `api.publishPost({ postId })` with both sides of the schema inferred. */
+/**
+ * `api.publishPost({ postId })` with both sides of the schema inferred; a stream-declaring action's
+ * method also carries `.stream(input)`, and only that one — the type is the gate.
+ */
 export type Client<TActions extends ActionMap> = {
-  readonly [K in keyof TActions]: TActions[K] extends Action<infer TIn, infer TOut>
-    ? ClientMethod<TIn, TOut>
-    : never;
+  readonly [K in keyof TActions]: TActions[K] extends StreamAction<
+    infer TIn,
+    infer TOut,
+    infer TChunk
+  >
+    ? StreamClientMethod<TIn, TOut, TChunk>
+    : TActions[K] extends Action<infer TIn, infer TOut>
+      ? ClientMethod<TIn, TOut>
+      : never;
 };
 
 export type ClientMethod<TIn extends StandardSchemaV1, TOut extends StandardSchemaV1> = (
@@ -70,6 +84,22 @@ export type ClientMethod<TIn extends StandardSchemaV1, TOut extends StandardSche
   options?: CallOptions,
 ) => Promise<InferOutput<TOut>>;
 
+/**
+ * A stream-declaring action's method: the ordinary call, plus `.stream(input)` — each chunk as the
+ * server yields it, and the generator's RETURN value is the output. `POST` with
+ * `accept: text/event-stream` through core's `clientStream`, never `EventSource`.
+ */
+export type StreamClientMethod<
+  TIn extends StandardSchemaV1,
+  TOut extends StandardSchemaV1,
+  TChunk extends StandardSchemaV1,
+> = ClientMethod<TIn, TOut> & {
+  stream(
+    input: InferInput<TIn>,
+    options?: Omit<CallOptions, 'retry'>,
+  ): AsyncGenerator<InferOutput<TChunk>, InferOutput<TOut>, undefined>;
+};
+
 /** Core's one declaration, re-exported by name so `import type { FetchLike }` keeps resolving. */
 export type { FetchLike } from '@ultimat3/core';
 
@@ -125,12 +155,17 @@ export function rpc<TActions extends ActionMap>(options: ClientOptions): Client<
 export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
   name: string,
   options: ClientOptions,
-  pinnedPath?: string,
+  pinned?: ActionHttp,
 ): ClientMethod<TInput, TOutput> {
   // No default here: for a caller naming no style, `actionPath` asks the document the server
   // rendered, and that answer must be the same one `useMutation` and the outbox replay get.
-  const path = pinnedPath ?? actionPath(name, options.pathStyle);
-  const url = `${options.baseUrl.replace(/\/+$/, '')}${path}`;
+  // A pin by name (`rpc`) is the one the server stamped into this document (`renderedActionPin`);
+  // a declaration's own (`.client()`) wins, and with neither the style derives the path. A
+  // declared method with no path still names the verb when no stamp does (a server has none).
+  const pin = pinned?.path === undefined ? renderedActionPin(name) : pinned;
+  const path = pin?.path ?? actionPath(name, options.pathStyle);
+  const method = pin?.method ?? pinned?.method ?? 'POST';
+  const base = options.baseUrl.replace(/\/+$/, '');
   const onResponse = (response: Response): void =>
     assertSameBuild(options.buildId, response.headers.get(BUILD_ID_HEADER), name);
   const decodeError = (
@@ -139,11 +174,19 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
     retryAfterSeconds?: number,
   ): UltimateError | undefined => toUltimateError(text, status, name, retryAfterSeconds);
   // Erased at the wire seam; the response type is this action's by construction.
-  return (input, callOptions = {}) =>
-    clientTransport({
-      method: 'POST',
+  const call: ClientMethod<TInput, TOutput> = (input, callOptions = {}) => {
+    let wire: { readonly url: string; readonly body: unknown };
+    try {
+      wire = wireOf(name, base, path, input);
+    } catch (error) {
+      // A rejection like every other refusal of a call, never a throw out of a Promise-returning one.
+      return Promise.reject(error);
+    }
+    const { url, body } = wire;
+    return clientTransport({
+      method,
       url,
-      body: input ?? {},
+      body,
       headers: headersFor(options),
       signal: callOptions.signal,
       idempotencyKey: callOptions.idempotencyKey,
@@ -156,6 +199,52 @@ export function clientMethodFor<TInput extends StandardSchemaV1, TOutput extends
       decodeError,
       fetchImpl: options.fetch,
     }) as Promise<InferOutput<TOutput>>;
+  };
+  // On every method, because the name-only `rpc` proxy cannot see a declaration: the TYPE offers
+  // it only where the action streams, and a server that does not stream answers JSON, which
+  // `clientStream` returns as the output. Never retried: a stream is not an idempotent replay.
+  async function* stream(
+    input: InferInput<TInput>,
+    callOptions: Omit<CallOptions, 'retry'> = {},
+  ): AsyncGenerator<unknown, InferOutput<TOutput>, undefined> {
+    // Inside the generator, so a refusal arrives on the first pull like every other one.
+    const { url, body } = wireOf(name, base, path, input);
+    return (yield* clientStream<unknown, InferOutput<TOutput>>({
+      url,
+      body,
+      headers: headersFor(options),
+      signal: callOptions.signal,
+      idempotencyKey: callOptions.idempotencyKey,
+      onResponse,
+      decodeError,
+      fetchImpl: options.fetch,
+    })) as InferOutput<TOutput>;
+  }
+  return Object.assign(call, { stream });
+}
+
+/**
+ * A `:param` pin's URL, filled from the input the way the server's router reads it back (each value
+ * one encoded segment), and the body without those keys — the URL carries them. A static path is
+ * the whole input as the body, as every unpinned call always sent. A missing value is refused
+ * before any request exists.
+ */
+function wireOf(
+  name: string,
+  base: string,
+  path: string,
+  input: unknown,
+): { readonly url: string; readonly body: unknown } {
+  const filled = fillWire(path, input);
+  if (!filled.ok) {
+    throw new ActionHttpPathInvalidError({
+      name,
+      path,
+      reason: `:${filled.missing} ${filled.reason}`,
+      fix: `${name}.client(options)({ ${filled.missing}: '<value>', ... }) — a non-empty string, the URL's :${filled.missing}`,
+    });
+  }
+  return { url: `${base}${filled.url}`, body: filled.rest ?? {} };
 }
 
 /** One attempt, and no retry at all. What a mutation carrying no idempotency key is allowed. */
@@ -223,6 +312,7 @@ function toUltimateError(
     // is dropped rather than repaired, and `cause` below still carries every rejection in it.
     issues: issuesFromWire(body['issues']),
     meta: metaFromWire(body['meta']),
+    requestId: body['requestId'],
     cause: stringOr(body['cause'] ?? body['detail'], `${name} failed with ${status}`),
     fix: stringOr(body['fix'], `x actions show ${name} --json`),
     // RFC-9457's `type` IS a documentation URI, so a server that sends no `docs` extension has