Actions

The load-bearing primitive. A mutation or command, server-authoritative, declared once.

export const publishPost = action({
  input:  t.object({ postId: t.uuid, notify: t.boolean.default(true) }),
  output: PostView,
  policy: can('post:publish', ({ input, actor }) => ownsPost(actor, input.postId)),
  cache:  { invalidates: [tag.post, tag.feed] },
  mcp:    { expose: true, description: 'Publish a draft post' },
  async handle({ input, ctx }) {
    const post = await ctx.posts.publish(input.postId);
    if (input.notify) await notifySubscribers.enqueue({ postId: post.id, orgId: post.orgId });
    return post;
  },
});

Declared one per file in a feature's actions/ (actions/publish-post.ts, what x g writes). Named export, never default. The export name is the identity, and it must be globally unique. Only the HTTP path is derived from it (publishPost → POST /api/posts/publish); the OpenAPI operationId and the MCP tool name are the export name verbatim — publishPost, never publish_post. As of 2026-08 that holds on every surface at once: what tools/call accepts, what defineAppMcp's scopes: map is keyed on, what the LLM tool list offers, what openapi.json's x-ultimate.mcpTool publishes, and what describe().mcp.tool reports.

Fields

.sensitive() on an input field — cardPan: t.string.sensitive() — means sent in, never written down by the framework, never sent back (JSON Schema writeOnly). Reach, exactly: the audit: true record's input and x jobs show hold [redacted], read from THIS action's own schema, so another action's cardPan and the idempotency store are untouched. Not your own logger.info('x', input): that line holds no schema — use redactKeys or a Secret there. A refusal's issue carries rule (string.min, enum, … — SCHEMA_RULES) and params ({ min: 3 }) on the wire, so a form translates on the rule, never the English message.

ctx members an action may use:

Usage meters: meter:

A meter counts calls per tenant per period, durably, inside invoke. Prices, plans and the payment provider stay with the app: the framework resolves a number from ctx and counts the draw. As of 2026-11.

import { action, t } from '@ultimat3/action';
import { allow } from '@ultimat3/policy';

const PER_DAY = new Map([['org-free', 500]]);
const quotaWarning = { enqueue: async () => undefined }; // in an app: a job({ input: MeterWarning, … })

export const callTool = action({
  input: t.object({ prompt: t.string }),
  output: t.object({ ok: t.boolean }),
  policy: allow(),
  rateLimit: { windowMs: 60_000, limit: ({ ctx }) => (ctx.actor.orgId === undefined ? 10 : 60) },
  meter: {
    name: 'calls',
    period: 'day',
    limit: ({ ctx }) => PER_DAY.get(ctx.actor.orgId ?? '') ?? 0,
    warnAt: 0.8,
    onWarn: quotaWarning,
  },
  handle: () => ({ ok: true }),
});

Streaming: stream: and an async generator

An action that answers in pieces declares stream: <chunk schema> and writes handle as async *handle({ input, ctx }): each yield is a chunk, the return is the output.

A chunk its schema refuses, or stream: beside a handle that is not a generator, is X_ACTION_STREAM_INVALID. The OpenAPI 200 lists text/event-stream beside application/json for a streaming action only. agent() streams this way.

The fluent surface

Every projection this package owns is a method on the action — publishPost.openapi(), never toOpenApiOperation(publishPost). The MCP tool is the exception by tier: @ultimat3/mcp's one projection, toolFrom(publishPost) (As of 25.0.0 there is no .tool()). Exactly four declared fields are lifted onto it as readable properties: input, output, policy, mcp. The rest of the declaration is structured metadata, reachable through describe() and nowhere else. An action has no .def.

handle and row — the declaration's two functions — are unreachable by design: neither lifted nor described. The declaration lives in a private store inside invoke.ts and @ultimat3/action exports no reader for it, so invoke is the only thing that can run them — one execution path and one authz path, structurally rather than by convention. A hand-rolled object with kind: 'action' is X_ACTION_FOREIGN, never a registered action.

Every projection needs the name defineApi({ actions }) stamps on at boot. It names the export in place, so import { publishPost } is the action that projects once the app has booted — there is no second, differently-named twin to remember.

Six generated artifacts

A client for code that cannot import the app. rpc needs the app's action types, so a customer's TypeScript never had one. x client customer --out <dir> compiles the committed openapi.json (or a bearer mount's own document, --mount /v1) into index.ts + types.ts with no import beyond the platform: createClient({ baseUrl, headers }), one method per operationId, a non-2xx as ProblemError, and refusalOf(error, 'publishPost') narrowing to the codes that operation declares under errors:. The calling direction is x client vendor <name> — outbound() and t schemas from a third party's document. One compiler for both, never a second way: CLI reference. As of 2026-11.

A bulk endpoint is one action. hive({ member, split, onMemberError }) (@ultimat3/ai) runs member once per item under its own policy and answers per-item outcomes — { index, status: 'ok' | 'failed', … } — so a bulk operation is in OpenAPI, the typed client, the customer client and MCP by construction, with no batch route to hand-write.

Plus cache invalidation: cache.invalidates fans out to request memo, in-process LRU (all instances, over NATS), Redis, ISR pages, and the CDN purge webhook in one hop (Caching and invalidation).

There is one execution path. HTTP, MCP, jobs, and direct server calls differ only in the surface they declare, which selects how a denial is rendered — never whether authz runs and never how input is validated.

The API as a whole — defineApi({ http, openapi })

As of 22.6.0. Declared once, beside the primitives, and read by the boot and x manifest:

One authz system

policy is evaluated for the HTTP call, the typed client call, the job execution, the MCP tool call, and the live-query subscription — the same function, the same actor resolution, the same denial error.

Two authz systems is how every Meteor-like framework died. Meteor had allow/deny rules for the client sync path and plain method bodies for the server path; the two drifted, and the drift was the security model. Anything that lets an agent expose data through a second door — a "public" MCP tool, an "internal" RPC, a sync rule table — is a rejected design, not a config option.

Rejected by that rule: an MCP-specific permission table, a "trusted tool" mode, a broad-rights service account for agents, and an internal RPC surface that skips policy. Details in Policies and authz.

action must never

• read the request object, headers, or cookies directly — actor and tenant come from ctx. One exception is a caller whose credential is a signature over the raw body — a signed upload. useRequestBodyBytes() from @ultimat3/http returns the exact bytes the body was parsed from (the same size-capped, cached read). Off HTTP (a job, MCP) it is X_NO_REQUEST. A vendor's webhook never comes through an action: the input schema answers 400/422 before the signature is checked, and application/xml, application/octet-stream or no content type is X_BODY_INVALID with the handler never reached. The one door is webhookReceiver() (Jobs and workflows)
• render, redirect, or return HTML
• perform its own authorization inside handle — that belongs in policy
• do slow work inline — enqueue a job
• share a file with another primitive — one per file, in the feature's actions/

Logic lives in service.ts; actions/ holds declarations. An action whose handle is more than a few lines of orchestration is a service waiting to be extracted.

mutator — action + optimistic twin

Same declaration surface as action, plus a local half that runs client-side against the local store while the server call is in flight.

export const likePost = mutator({
  // REQUIRED (`X_MUTATOR_NOT_IDEMPOTENT`): a replay under the same Idempotency-Key answers the
  // first result instead of running `server` again.
  idempotent: true,
  // Convergent, not incremental: `local` replays on every rebase, so applying it N times has to
  // equal applying it once — `likedByMe` is what makes the second application a no-op.
  local(tx, { postId }) {
    tx.posts.update(postId, (p) =>
      p.likedByMe ? {} : { likedByMe: true, likeCount: p.likeCount + 1 });
  },
  async server(ctx, { postId }) { return ctx.posts.like(postId); },
  conflict: 'server-wins', // | 'last-write-wins' | custom(merge)
});

Replayability rule: local is re-executed on every rebase — after each server confirmation, on reconnect, and when a conflicting remote write arrives. It must be a pure function of (tx, input). I/O, Math.random(), crypto.randomUUID(), or a wall-clock read makes the local timeline diverge from the server's, and the divergence surfaces as flicker, then as wrong data. Ids and timestamps come from the input, generated once at call time. Tier 3 local-first (persist: true) has not shipped, As of 2026-08; mutators work today at realtime tiers 1–2 (Realtime).

Errors

X_ACTION_POLICY_MISSING: action registered without a policy
  cause: action "publishPost" was registered without a policy
  fix:   add `policy: can('publishPost')` to the action definition in the file that exports it

Every code carries the same { code, cause, fix, docs } in the terminal, the dev overlay, the HTTP body, --json, and the MCP tool error. Full list: Error codes.

A handler's OWN refusals are app codes, each declared once with defineError from @ultimat3/core — the title, the status the HTTP projection answers and the class handle throws:

import { defineError } from '@ultimat3/core';

export const PostNotFound = defineError<string>({
  code: 'X_POST_NOT_FOUND',
  title: "no such post in the actor's organisation",
  status: 404,
  cause: (ref) => `no post ${ref} in the actor's organisation`,
  fix: 'x queries list --json, then pass an id the post read returns',
});

// in handle: throw new PostNotFound(input.postId);

A code with no status answers 500 and hides its cause from the caller; offSocket: true declares a code no response carries. guards/error-declared.ts refuses a handwritten UltimateError subclass.

Declared refusals (errors:)

errors: [PostNotFound.code, 'X_FORBIDDEN'] names the 4xx codes a caller may branch on. Import the class and list its .code: the import is what registers the status before the list is checked. Judged at the one place a handler runs: a throw out of handle or row only — the policy, the parse, the rate limit and idempotency sit outside, so X_FORBIDDEN from the policy or X_INPUT_INVALID is never judged.

• OpenAPI: each code joins responses[status]. A status only the list answers narrows Problem.type to an enum of urn:ultimate:error:<CODE>; a status the framework already answers (400, 403, 409) keeps its open Problem and names the code in its description. Both carry x-ultimate-errors: [<codes>]. Undeclared, the document's bytes are unchanged.
• .contract() gains one assertion: a code literal or a defineError class in handle's or row's own source, 4xx and outside the list, fails it. First hop only — a code thrown behind a helper is judged when a test reaches it (the generated exercise runs included). A path nothing reaches stays unjudged; a class imported under another name is missed by the scan.
• MCP and the in-app agent's tool: the description ends Declared refusals: <codes>.
• Nested invoke: an inner action's declared refusal is the outer's to declare too — the outer's caller receives it.
• x.manifest.json: errors on the action's fact; removing a code is breaking, adding one additive.

Introspection

$ x actions list --json
{"ok":true,"command":"actions","summary":"1 action","findings":[],
 "data":[{"kind":"action","mutator":false,"name":"publishPost","verb":"publish",
   "resource":"posts","method":"POST","path":"/api/posts/publish",
   "capability":"post:publish", …}]}

Both subcommands emit the same describe() row — list one per action, show the named one. It is exactly what publishPost.describe() returns in process, so the CLI has no private view of a primitive:

$ x actions show publishPost --json
{"ok":true,"command":"actions","summary":"action publishPost","findings":[],
 "data":{"kind":"action","mutator":false,"name":"publishPost","verb":"publish",
  "resource":"posts","method":"POST","path":"/api/posts/publish",
  "capability":"post:publish",
  "input":{"type":"object","required":["postId"],
    "properties":{"postId":{"type":"string","format":"uuid"},
                  "notify":{"type":"boolean","default":true}}},
  "output":{"$ref":"#/components/schemas/PostView"},
  "invalidates":["feed","post"],"idempotent":false,
  "mcp":{"expose":true,"tool":"publishPost","description":"Publish a draft post"},
  "rateLimit":null}}

invalidates is sorted and de-duplicated, so descriptor output never depends on declaration order — a diffable contract. mutator is true only for a mutator() declaration; kind stays "action" for both, which is why the flag is a field of its own and not a second kind. The same data is the MCP actions.describe tool (actions and queries in one call) and the /_x Routes panel.

Generated contract test

Emitted with the action, and green on the first run: it pins the invariant the action owns — a non-owner is denied — rather than a TODO someone has to notice.

// contract test — generated with the action
test('publishPost denies a non-owner', async ({ seed, actorFor }) => {
  const { post, stranger } = await seed('two-orgs');
  await expect(publishPost.as(actorFor(stranger), { postId: post.id }))
    .rejects.toBeUltimateError('X_FORBIDDEN');
});

Runs against a cloned Postgres (CREATE DATABASE … TEMPLATE), never a mock. x test contract asserts the input/output schema round-trip, one denial per policy branch, and that the emitted OpenAPI operation plus MCP tool shape still match the declaration. See Testing.