@ultimat3/action 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @ultimat3/action ⚡
+
+One declaration → six artifacts.
+
+| # | Artifact | Reach it with | Guarantees |
+|---|---|---|---|
+| 1 | HTTP route `POST /api/<resource>/<verb>` | `toRoute(publishPost)` — the server mounts it | policy + validation + idempotency + invalidation, non-optional |
+| 2 | OpenAPI 3.1 operation + document | `publishPost.openapi()` / `buildOpenApi()` | byte-stable output, diffed by `x verify` |
+| 3 | Typed RPC client | `publishPost.client({ baseUrl })` / `rpc<Api['actions']>()` | server typo = compile error in Solid |
+| 4 | MCP tool | `publishPost.tool()` | *identical* policy evaluation to the route |
+| 5 | Job handle | `publishPost.job()` | enqueue durable work, no rewrite |
+| 6 | Contract tests | `publishPost.contract()` | garbage rejected, anonymous denied, spec present |
+
+## The fluent surface
+
+An action carries its own projections, so app code never reaches through `.def` and
+never imports a projection function:
+
+```ts
+publishPost.input                              // the declared input schema
+publishPost.output                             // the declared output schema
+publishPost.policy                             // the one policy object
+publishPost.mcp                                // { expose, description }, as declared
+await publishPost.as(actor, { postId })        // run as someone, one execution path
+publishPost.tool()                             // MCP descriptor
+publishPost.openapi()                          // OpenAPI operation
+publishPost.client({ baseUrl })                // typed RPC method
+publishPost.job()                              // durable-work handle
+publishPost.contract()                         // the three generated assertions
+```
+
+`publishPost.tool().policy === publishPost.policy` — the same object, so an MCP call
+cannot reach a different authz path. `.as()` keeps the surrounding context whole and
+swaps only the actor: impersonation, not a second context.
+
+## Declare
+
+`t` is re-exported here — the same object `@ultimat3/schema` exports, so an action file
+imports one package for the primitive and its schemas, never two.
+
+```ts
+import { action, t } from '@ultimat3/action';
+
+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' },
+  idempotent: true,
+  async handle({ input, ctx }) {
+    const post = await ctx.posts.publish(input.postId);
+    if (input.notify) await notifySubscribers.enqueue({ postId: post.id });
+    return post;
+  },
+});
+```
+
+## Register — one call, at boot
+
+`apps/web/api/index.ts` is the whole API surface. Importing it IS the boot.
+
+```ts
+import { defineApi } from '@ultimat3/action';
+import * as postActions from '../app/posts/actions';
+import * as postMutators from '../app/posts/mutator';
+import * as postQueries from '../app/posts/live';
+
+export const api = defineApi({
+  actions: [postActions],
+  mutators: [postMutators],
+  queries: [postQueries],
+});
+
+export type Api = typeof api;
+```
+
+| Key | Goes to | Why |
+|---|---|---|
+| `actions` | the action registry | the primitive |
+| `mutators` | the action registry | a mutator IS an action, on the same authz path |
+| `llm` | the action registry | `llm()` returns an action, not a ninth primitive |
+| `queries` | `@ultimat3/query`'s registry, via core's registrar table | `query` is on this tier, so importing it here would be a build error |
+
+Names come from **export names** — that is what makes the path, the tool name and the
+OpenAPI `operationId` derivable everywhere without a second declaration. Registration
+stamps the name onto the action the module exported, so the binding you imported is the
+one that projects; a projection attempted before boot is `X_ACTION_UNREGISTERED`. Two
+features exporting one name collide with `X_ACTION_DUPLICATE` rather than merging.
+
+`registerActions` / `registerQueries` are what `defineApi` composes. An app calling them
+directly is a second path.
+
+## Call it — `rpc`
+
+```ts
+import { rpc } from '@ultimat3/action';
+import type { Api } from '../api';
+
+export const client = rpc<Api['actions']>({ baseUrl: '/' });
+```
+
+`Api['actions']` is the merged module type, so `client.publishPost` is typed from the
+declaration with no codegen step. `Api` is imported as a **type only**, which is what keeps
+a page's module graph free of any edge to a feature's implementation.
+
+## Path derivation
+
+First camelCase word is the verb; the rest is the resource, last word pluralized,
+kebab-cased. The **MCP tool name is not derived** — it is the export name verbatim, because
+that is what `defineAppMcp`'s `scopes:` and a `tools/call` have to spell.
+
+| Action | Route | MCP tool |
+|---|---|---|
+| `publishPost` | `POST /api/posts/publish` | `publishPost` |
+| `updateUserProfile` | `POST /api/user-profiles/update` | `updateUserProfile` |
+| `likePost` | `POST /api/posts/like` | `likePost` |
+| `checkout` (single word) | `POST /api/checkouts/invoke` | `checkout` |
+
+## One invocation core
+
+`invoke()` is the only execution path: **parse input → evaluate policy → handle →
+parse output**. HTTP, MCP, jobs and direct server calls differ **only** in the
+`surface` they hand to `enforce()` from `@ultimat3/policy`, which selects how a
+denial renders (problem+json / tool error / failed job) — never whether authz runs.
+
+Enforced structurally, not by convention: the declaration is held in a private
+store inside `invoke.ts`, so `handle` is reachable from nowhere else. An action has
+no `.def`. A second authz path cannot be written without deleting that store.
+
+| Stage | Failure |
+|---|---|
+| parse input | `X_INPUT_INVALID` |
+| evaluate policy | the policy's own code — `X_UNAUTHENTICATED` (401), `X_FORBIDDEN` (403) |
+| handle | whatever the handler throws |
+| parse output | `X_OUTPUT_INVALID` — and fields the schema never declared are dropped |
+
+Registering an action without `policy:` throws `X_ACTION_POLICY_MISSING`; there is
+no bypass flag. A look-alike that never came out of `action()` is `X_ACTION_FOREIGN`.
+
+## mutator = action + local twin
+
+`mutator()` is built **on top of** `action()`. A mutator IS an action, so it gets all
+six projections; it adds `local(tx, input)` for the optimistic write and a `conflict`
+strategy for the rebase.
+
+```ts
+export const likePost = mutator({
+  input: t.object({ postId: t.uuid }),
+  output: PostLikes,
+  policy: can('post:like'),
+  // 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)
+});
+```
+
+The projected surface carries the same three names the declaration used, on top of
+every action member above:
+
+```ts
+likePost.local(tx, { postId })            // the optimistic write, replayed on rebase
+await likePost.server(ctx, { postId })    // the authoritative write
+likePost.conflict                         // the declared strategy
+```
+
+`.server()` is not a shortcut past `invoke` — it calls the action's own callable, so
+the input parse, the policy and the output parse all still run: an actor the policy
+denies is denied there exactly as over HTTP. `.local()` is the only half that skips
+the core, because it never leaves the client; keep it a pure function of `(tx, input)`
+— no I/O, no clock, no randomness — since every rebase replays it.
+
+`LocalTx` is the client write surface (`@ultimat3/realtime` implements it over OPFS
+SQLite). Type your tables once: `declare module '@ultimat3/action' { interface
+LocalTables { posts: PostRow } }`.
+
+## Determinism + idempotency
+
+`serializeOpenApi(buildOpenApi())` sorts keys at every depth, iterates the registry
+name-sorted, and reads no clock, env or random source — same registry ⇒ same bytes ⇒
+`x verify` can diff the spec and fail on `X_CONTRACT_DRIFT`.
+
+`idempotent: true` + an `Idempotency-Key` header replays the first response
+(`x-ultimate-replayed: 1`); a duplicate still in flight, or a reused key with a new
+payload, is `X_IDEMPOTENCY_CONFLICT`. Store is swappable via `setIdempotencyStore()`.
+
+## Errors
+
+| Code | When | Fix |
+|---|---|---|
+| `X_ACTION_DUPLICATE` | two actions registered under one name | rename one export |
+| `X_ACTION_POLICY_MISSING` | registration without `policy:` | add `policy: can('…')` |
+| `X_INPUT_INVALID` | input failed the Standard Schema | `x actions describe <name> --json` |
+| `X_IDEMPOTENCY_CONFLICT` | key reused with a new payload / still in flight | new key, or retry later |
+| `X_CONTRACT_DRIFT` | client/server build skew, missing spec entry | reload / `x verify --contract` |
+| `X_RPC_FAILED` | non-`problem+json` failure reached the client | check the gateway |
+| `X_ACTION_UNREGISTERED` | projected before `registerActions()` ran | register at boot |
+
+Denials re-throw the policy layer's own codes (`X_FORBIDDEN`, `X_UNAUTHENTICATED`) —
+this package never invents an authz code.
+
+## Boundaries
+
+Tier 3. Imports `@ultimat3/core`, `schema`, `cache`, `policy`, `http`. Never imports
+`query`, `jobs`, `realtime` (same tier) or anything above it — those import *this*.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ultimat3/action",
+  "version": "1.0.0",
+  "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/action"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/cache": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/http": "1.0.0",
+    "@ultimat3/policy": "1.0.0",
+    "@ultimat3/schema": "1.0.0"
+  }
+}

package/src/action.ts

@@ -0,0 +1,295 @@
+/**
+ * The `action` primitive: one server-authoritative mutation, declared once.
+ * Every projection in this package (route, OpenAPI, client, MCP tool, job
+ * handle, contract tests) reads this declaration — none of them re-declare it.
+ */
+
+import type { CacheTag } from '@ultimat3/cache';
+import type { Actor, Ctx } from '@ultimat3/core';
+import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { ClientMethod, ClientOptions } from './client';
+import type { ContractTest, ContractTestOptions } from './contract-test';
+import { facadeFor } from './facade';
+import type { OpenApiOperation } from './http';
+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 { McpToolDescriptor } from './mcp-tool';
+import { derivePath, toToolName } from './naming';
+import { type ActionPolicy, policyCapability, type Surface } from './policy-gate';
+import { tagKeys } from './tags';
+
+export interface ActionCache {
+  /** Tags dropped from every cache tier after the handler settles. */
+  readonly invalidates: readonly CacheTag[];
+}
+
+export interface ActionMcp {
+  /** Opt-in: only a literal `true` makes the action a tool. Silence exposes nothing. */
+  readonly expose: boolean;
+  /**
+   * Contract text, NOT UI text — deliberately outside `t()`. It becomes the OpenAPI
+   * operation `summary` (`toOpenApiOperation`), and `buildOpenApi`'s bytes are what
+   * `x verify` diffs for contract drift. Resolving it through the ambient, request-scoped
+   * translator would make `openapi.json` depend on whichever locale happened to be active
+   * when it was generated, which is exactly the determinism that file's header forbids.
+   * Localised agent-facing text needs a separate, locale-resolved projection; there is no
+   * second field for it here until that exists, because two ways to describe one tool is
+   * the drift axiom 1 rejects.
+   */
+  readonly description?: string;
+  /**
+   * Roles that may SEE the projected tool. A CATALOG audience, never an authz rule — the
+   * `policy` above still decides every call, and this list decides nothing about one. Omitted
+   * means every caller may enumerate it.
+   *
+   * Fail-closed where it lands (`@ultimat3/mcp`): a caller whose role is not named — including
+   * one carrying no role at all — gets the answer an ABSENT tool gets, never `Forbidden`.
+   * Forbidden would confirm the tool exists, which turns the catalog into something an agent
+   * can enumerate by probing names.
+   *
+   * A plain role list, never a predicate: a declared fact has to stay static and serialisable.
+   * A surface deriving visibility from something richer (`@ultimat3/admin` derives it from the
+   * actor's admin permissions) hands `@ultimat3/mcp` a predicate instead.
+   */
+  readonly visibleTo?: readonly string[];
+}
+
+export interface ActionRateLimit {
+  readonly limit: number;
+  readonly windowMs: number;
+}
+
+export interface ActionHandlerArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+/** What a row loader gets: the parsed input and the context, never the request. */
+export interface ActionRowArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface ActionDef<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TRow = unknown,
+> {
+  readonly input: TInput;
+  readonly output: TOutput;
+  readonly policy: ActionPolicy<TRow>;
+  readonly cache?: ActionCache;
+  readonly mcp?: ActionMcp;
+  readonly rateLimit?: ActionRateLimit;
+  /** Marks the action safe to retry with an `Idempotency-Key`. */
+  readonly idempotent?: boolean;
+  /**
+   * Loads the row a row-level `policy` decides about, once per invocation, after the
+   * input parse and before the guard. This is the async half authz is not allowed to
+   * have: a predicate stays synchronous — a live query re-evaluates one per subscriber
+   * on every change, so an `await` inside it would be a database round trip per row per
+   * connected client. The caller loads what the rule needs and passes it in; here, the
+   * caller is the framework.
+   *
+   * Omitted means the rule decides on input alone and `row` reaches it as `null`. A rule
+   * that reads `row` must therefore fail closed on `null`, because "no loader declared"
+   * and "row not found" are the same value and neither is evidence of permission.
+   */
+  row?(args: ActionRowArgs<TInput>): TRow | null | Promise<TRow | null>;
+  handle(args: ActionHandlerArgs<TInput>): Promise<InferOutput<TOutput>> | InferOutput<TOutput>;
+}
+
+export interface InvokeOptions {
+  /** Explicit context. Omitted means "take the ambient request context". */
+  readonly ctx?: Ctx;
+  /**
+   * Run as someone else. Omitted keeps the context's own actor; `null` is the
+   * signed-out caller. The rest of the context is untouched, so impersonation
+   * stays on the one execution path instead of forking a second one.
+   */
+  readonly actor?: Actor | null;
+  readonly surface?: Surface;
+  readonly idempotencyKey?: string | null;
+  readonly store?: IdempotencyStore;
+  readonly onReplay?: () => void;
+}
+
+export interface McpDescriptorMeta {
+  readonly expose: boolean;
+  readonly tool: string;
+  readonly description: string | null;
+}
+
+export interface ActionDescriptor {
+  readonly kind: 'action';
+  /**
+   * Built by `mutator()`. `kind` cannot carry this: `describeActions()` hands back
+   * `ActionDescriptor`, whose `kind` is the literal `'action'` for a mutator too — so every
+   * reader downstream (`x.manifest.json`'s mutator count included) sees zero without it.
+   */
+  readonly mutator: boolean;
+  readonly name: string;
+  readonly verb: string;
+  readonly resource: string;
+  readonly method: 'POST';
+  readonly path: string;
+  readonly capability: string;
+  readonly input: JsonSchemaObject;
+  readonly output: JsonSchemaObject;
+  readonly invalidates: readonly string[];
+  readonly idempotent: boolean;
+  readonly mcp: McpDescriptorMeta;
+  readonly rateLimit: ActionRateLimit | null;
+}
+
+/**
+ * Schema-erased view of a definition, held only by `invoke.ts`'s private store —
+ * never reachable from an action. Members stay method-syntax on purpose:
+ * bivariant parameters are what make the erasure assignable.
+ */
+export interface AnyActionDef {
+  readonly input: StandardSchemaV1;
+  readonly output: StandardSchemaV1;
+  readonly policy: ActionPolicy;
+  readonly cache?: ActionCache;
+  readonly mcp?: ActionMcp;
+  readonly rateLimit?: ActionRateLimit;
+  readonly idempotent?: boolean;
+  row?(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
+  handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
+}
+
+export interface AnyAction {
+  readonly kind: 'action';
+  readonly name: string;
+  /** The declaration, minus `handle`: readable, and never a way to run it. */
+  readonly input: StandardSchemaV1;
+  readonly output: StandardSchemaV1;
+  readonly policy: ActionPolicy;
+  readonly mcp?: ActionMcp;
+  describe(): ActionDescriptor;
+  /** A twin under another name. Registration uses `nameAction`, which names in place. */
+  named(name: string): AnyAction;
+  /** Run as this actor. Same `invoke` core, only the context's actor changes. */
+  as(actor: Actor | null, input: unknown, options?: InvokeOptions): Promise<unknown>;
+  tool(): McpToolDescriptor;
+  openapi(): OpenApiOperation;
+  contract(options?: ContractTestOptions): readonly ContractTest[];
+}
+
+export interface Action<
+  TInput extends StandardSchemaV1 = StandardSchemaV1,
+  TOutput extends StandardSchemaV1 = StandardSchemaV1,
+> extends AnyAction {
+  /** Callable server-side with the same types the client and MCP tool see. */
+  (input: InferInput<TInput>, opts?: InvokeOptions): Promise<InferOutput<TOutput>>;
+  readonly input: TInput;
+  readonly output: TOutput;
+  named(name: string): Action<TInput, TOutput>;
+  as(
+    actor: Actor | null,
+    input: InferInput<TInput>,
+    options?: InvokeOptions,
+  ): Promise<InferOutput<TOutput>>;
+  /**
+   * Typed against this action's schemas, which is the whole point of both — so they
+   * live here and not on the schema-erased `AnyAction` view.
+   */
+  client(options: ClientOptions): ClientMethod<TInput, TOutput>;
+  job(): ActionJobHandle<TInput, TOutput>;
+}
+
+/** 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' | 'tool' | 'openapi' | 'client' | 'job' | 'contract'
+>;
+
+export function action<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  TRow = unknown,
+>(def: ActionDef<TInput, TOutput, TRow>): Action<TInput, TOutput> {
+  return build(def, '');
+}
+
+/**
+ * Structural, not nominal: an object only counts as an action if `action()` built
+ * it, because only then does a declaration exist for `invoke` to run. A look-alike
+ * with `kind: 'action'` never reaches the registry or a projection.
+ */
+export function isAction(value: unknown): value is AnyAction {
+  return (
+    typeof value === 'function' && (value as { kind?: unknown }).kind === 'action' && hasDef(value)
+  );
+}
+
+/**
+ * Stamp the export name onto the action the app declared, rather than handing back a
+ * differently-named copy of it. `import { publishPost } from './actions'` is then the
+ * action that projects — `publishPost.tool()` after boot, with nothing to remember.
+ * Naming twice is the one case that still needs a twin: one object, one name, forever.
+ */
+export function nameAction<A extends AnyAction>(target: A, name: string): A {
+  if (target.name === name) return target;
+  if (target.name.length > 0) return target.named(name) as A;
+  Object.defineProperty(target, 'name', { value: name, configurable: true });
+  return target;
+}
+
+function build<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1, TRow>(
+  def: ActionDef<TInput, TOutput, TRow>,
+  name: string,
+): Action<TInput, TOutput> {
+  const callable = (
+    input: InferInput<TInput>,
+    opts: InvokeOptions = {},
+  ): Promise<InferOutput<TOutput>> =>
+    // `invoke` is schema-erased; the output type is this action's by construction.
+    invoke(self, input, opts) as Promise<InferOutput<TOutput>>;
+
+  const self: Action<TInput, TOutput> = Object.assign(callable, {
+    kind: 'action' as const,
+    describe: (): ActionDescriptor => describeAction(self),
+    named: (next: string): Action<TInput, TOutput> => build(def, next),
+    ...facadeFor(def, () => self),
+  });
+  // `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);
+  return self;
+}
+
+export function describeAction(target: AnyAction): ActionDescriptor {
+  const name = actionName(target);
+  const def = defOf(target);
+  const path = derivePath(name);
+  const mcp = def.mcp;
+  return {
+    kind: 'action',
+    // The brand `mutator()`'s `wrap` stamps on the action it lifted, read structurally.
+    // Importing `isMutator` would point this module at the one that already imports it, for a
+    // check that needs the brand and not the predicate — `defOf` above already proved the rest.
+    mutator: (target as { readonly isMutator?: unknown }).isMutator === true,
+    name,
+    verb: path.verb,
+    resource: path.resource,
+    method: 'POST',
+    path: path.path,
+    capability: policyCapability(def.policy),
+    input: jsonSchemaOf(def.input),
+    output: jsonSchemaOf(def.output),
+    invalidates: tagKeys(def.cache?.invalidates ?? []),
+    idempotent: def.idempotent === true,
+    mcp: {
+      expose: mcp?.expose ?? true,
+      tool: toToolName(name),
+      description: mcp?.description ?? null,
+    },
+    rateLimit: def.rateLimit ?? null,
+  };
+}