@ultimat3/action 22.9.1 → 22.11.0

package/CLAUDE.md

@@ -52,7 +52,8 @@ Owns the `action` + `mutator` primitives and their six projections. Tier 3.
 
 ## Invariants — execution and authz
 
-- Every surface goes through `invoke`: parse input, evaluate policy, handle, parse output. A second
+- Every surface goes through `invoke`: the policy's actor half (`guardBeforeInput`, 403 before the
+  parse), parse input, evaluate policy, handle, parse output. A second
   execution path is the one unforgivable change here.
 - **An explicit `ctx` is INSTALLED, never merely passed** — the ambient context (which
   `@ultimat3/entity`'s tenant guard reads) must be the identity `guard()` decided about.

package/README.md

@@ -256,8 +256,8 @@ the manifest never carried a tool name and was never wrong about one.
 
 ## 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
+`invoke()` is the only execution path: **policy's actor half → 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.
 
@@ -267,11 +267,20 @@ no `.def`. A second authz path cannot be written without deleting that store.
 
 | Stage | Failure |
 |---|---|
+| policy, actor half (`guardBeforeInput`) | `X_UNAUTHENTICATED` / `X_FORBIDDEN` for a caller the policy refuses whatever the input — never a 400 describing the schema of an operation they may not call |
 | 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 |
 
+**Who before what (`As of 2026-09`).** The actor half is the part of the policy that reads no
+input: `can(p)` with no predicate, `allow()`, `deny()`, their combinators, and `can(p, pred)` for
+an actor without `p`. It is decided before the parse — `decideBeforeInput` in `@ultimat3/policy`,
+exact rather than a heuristic — so `can('refund:issue')` answers a customer's `{}` with 403, and a
+staff caller's `{}` with the 400 naming each missing field. A predicate over `input` or `row` still
+runs after the parse, on the parsed value. Same on HTTP, MCP (including the `invalid-args`
+path) and `.as()`/jobs. An audited action's denied attempt still records the parsed input.
+
 `cache: { invalidates }` fans out **after** the handler commits, so it never fails it: a
 fan-out that refuses — an undeclared tag, `X_CACHE_TAG_UNKNOWN` — is one
 `action.invalidate.failed` log line and the entries expire by TTL. A replayed idempotent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.9.1",
+  "version": "22.11.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,11 +34,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.9.1",
-    "@ultimat3/core": "22.9.1",
-    "@ultimat3/entity": "22.9.1",
-    "@ultimat3/http": "22.9.1",
-    "@ultimat3/policy": "22.9.1",
-    "@ultimat3/schema": "22.9.1"
+    "@ultimat3/cache": "22.11.0",
+    "@ultimat3/core": "22.11.0",
+    "@ultimat3/entity": "22.11.0",
+    "@ultimat3/http": "22.11.0",
+    "@ultimat3/policy": "22.11.0",
+    "@ultimat3/schema": "22.11.0"
   }
 }

package/src/action.ts

@@ -63,6 +63,33 @@ export interface ActionMcp {
    * actor's admin permissions) hands `@ultimat3/mcp` a predicate instead.
    */
   readonly visibleTo?: readonly string[];
+  /**
+   * The tool's display name in an MCP client's UI (`title`, MCP 2025-06-18). Contract text, like
+   * `description`. Omitted: none is published and the client shows the tool name.
+   */
+  readonly title?: string;
+  /**
+   * MCP tool annotations, overriding what `@ultimat3/mcp` derives key by key. An action derives
+   * `readOnlyHint: false`, `destructiveHint: true` and `idempotentHint` from `idempotent`. Hints for
+   * a client's confirmation UI — the policy decides every call whatever they say.
+   *
+   * ```ts
+   * mcp: { expose: true, annotations: { destructiveHint: false, openWorldHint: true } },
+   * ```
+   */
+  readonly annotations?: McpAnnotationHints;
+}
+
+/**
+ * MCP's four tool hints, as the spec spells them. Declared here (tier 3) and in `@ultimat3/query`
+ * because `@ultimat3/mcp` (tier 4) is the reader and cannot be imported; its `McpToolAnnotations`
+ * is the same shape.
+ */
+export interface McpAnnotationHints {
+  readonly readOnlyHint?: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+  readonly openWorldHint?: boolean;
 }
 
 export interface ActionRateLimit {

package/src/contract-test.ts

@@ -12,6 +12,7 @@ import { actionName, invoke } from './invoke';
 import { derivePath } from './naming';
 import { buildOpenApi } from './openapi';
 import { describeSampleGap, sampleGaps, sampleInput } from './sample-input';
+import { validateInput } from './validate';
 
 export interface ContractTest {
   readonly name: string;
@@ -47,9 +48,12 @@ export function contractTestsFor(
   return [
     {
       name: `${name}: input schema rejects garbage`,
+      // The action's own parser — the one `invoke` runs — and never `invoke` itself: the policy's
+      // actor half is decided BEFORE the parse, so an anonymous caller of a guarded action is
+      // refused 401 without the schema ever seeing the garbage. The claim is about `input:`.
       run: async () => {
         await expectThrow(
-          () => invoke(target, garbage, { ctx, surface: 'http' }),
+          () => validateInput(target.input, garbage, name),
           'X_INPUT_INVALID',
           `${name} accepted the value this assertion sent as garbage`,
           `tighten \`input:\` in the ${name} definition`,
@@ -146,9 +150,10 @@ async function expectDenied(
     // drift error would hide the line that threw behind a fix that does not apply.
     if (!isUltimateError(error)) throw error;
     if (error instanceof ActionDeniedError) return;
-    // `invoke` runs parse input → row → policy → handle → parse output, and every stage lands
-    // here identically. Only `X_INPUT_INVALID` is attributable: it is what `validateInput`
-    // raises before `guard()` is reached, and `input:` is the knob that answers it. Any other
+    // `invoke` runs the policy's actor half → parse input → row → policy → handle → parse
+    // output, and every stage lands here identically. Only `X_INPUT_INVALID` is attributable: it
+    // is what `validateInput` raises before `guard()` is reached (for a policy whose actor half
+    // could not decide), and `input:` is the knob that answers it. Any other
     // code — `X_TENANCY_UNSCOPED` from a `row:` loader, `X_DB_CONFLICT` from a handler,
     // `X_OUTPUT_INVALID` from the parse after it — keeps its own code and its own fix rather
     // than being retold as an input problem with a fix that changes nothing.
@@ -184,11 +189,6 @@ async function expectThrow(
   } catch (error) {
     if (!isUltimateError(error)) throw error;
     if (error.code === code) return;
-    // `X_AUDIT_SINK_MISSING` is the one refusal `invoke` raises BEFORE the input parse, so
-    // "the schema accepted garbage" is a false statement about it and `input:` is not what
-    // answers it. It keeps its own code and its own runnable fix — the same rule `expectDenied`
-    // follows for every code it cannot attribute to `input:`.
-    if (error.code === 'X_AUDIT_SINK_MISSING') throw error;
     report();
     throw new ContractDriftError(`${cause} (got ${error.code}, expected ${code})`, fix);
   }

package/src/errors.ts

@@ -6,6 +6,7 @@
  */
 import {
   assertNever,
+  deniedCallerFix,
   ERROR_DOCS_URL,
   hasErrorCode,
   registerErrorCodes,
@@ -136,6 +137,7 @@ export class ActionDeniedError extends UltimateError {
       code,
       cause: `${action} denied: ${denialReason(denial)}`,
       fix: `x policy explain ${action} --json   # shows which clause decided and why`,
+      callerFix: deniedCallerFix(),
     });
     this.denial = denial;
   }
@@ -203,11 +205,25 @@ export class InputInvalidError extends UltimateError {
    * `formatIssues` here would pull that package's whole barrel into every browser bundle holding
    * the typed client.
    */
-  constructor(name: string, detail: string, issues?: readonly ValidationIssue[]) {
+  constructor(
+    name: string,
+    detail: string,
+    issues?: readonly ValidationIssue[],
+    /**
+     * What `name` names, in the cause: `'action'` (the default), or `'tool'` when `@ultimat3/mcp`
+     * refuses arguments against a tool's published schema — a query's or a meta tool's, not only an
+     * action's.
+     */
+    subject: 'action' | 'tool' = 'action',
+  ) {
     super({
       code: 'X_INPUT_INVALID',
-      cause: `input for action "${name}" failed validation: ${detail}`,
+      cause: `input for ${subject} "${name}" failed validation: ${detail}`,
       fix: `x actions describe ${name} --json  # prints the expected input schema`,
+      // A remote caller holds the published schema — the MCP `inputSchema`, the OpenAPI request
+      // body — and cannot run `x actions describe`.
+      callerFix:
+        'correct the fields named in cause to match the published input schema (the tool inputSchema, or the OpenAPI request body) and send again — the same input is refused the same way',
       ...(issues === undefined ? {} : { meta: { issues } }),
     });
     this.issues = issues;

package/src/index.ts

@@ -54,6 +54,7 @@ export type {
   ActionRowArgs,
   AnyAction,
   InvokeOptions,
+  McpAnnotationHints,
   McpDescriptorMeta,
 } from './action';
 export { action, describeAction, isAction } from './action';
@@ -247,6 +248,7 @@ export {
   actorOf,
   admitsAnonymous,
   guard,
+  guardBeforeInput,
   policyCapability,
   policyPermissions,
 } from './policy-gate';

package/src/invoke.ts

@@ -34,8 +34,8 @@ import { bustAfterCommit } from './cache-gate';
 import { ActionForeignError, ActionUnregisteredError } from './errors';
 import { getIdempotencyStore, withIdempotency } from './idempotency';
 import { idempotencyKeyFor } from './idempotency-key';
-import { actorOf, guard } from './policy-gate';
-import { validateInput, validateOutput } from './validate';
+import { actorOf, guard, guardBeforeInput } from './policy-gate';
+import { parsedOrNothing, validateInput, validateOutput } from './validate';
 
 /**
  * Private on purpose. `@ultimat3/action` exports no way to read this back, which
@@ -207,7 +207,7 @@ async function execute(
   });
 }
 
-/** The invocation itself, unwrapped: parse, load the row, guard, run, parse, bust. */
+/** The invocation itself, unwrapped: gate, parse, load the row, guard, run, parse, bust. */
 async function perform(
   def: AnyActionDef,
   name: string,
@@ -216,6 +216,18 @@ async function perform(
   options: InvokeOptions,
   trace: InvokeTrace,
 ): Promise<unknown> {
+  const surface = options.surface ?? 'server';
+  // Who is asking is decided before what they sent is read: a caller the policy refuses whatever
+  // the input is gets 403/401 here, not a 400 whose issues describe this action's input schema.
+  // Only the actor half runs — a predicate over `input` or `row` waits for `guard` below.
+  try {
+    guardBeforeInput(def.policy, { actor: actorOf(ctx), ctx, action: name }, surface);
+  } catch (denial) {
+    // The audit record still names what was attempted — the denial is already decided, so parsing
+    // now tells the CALLER nothing, and an unparseable payload is a record with no input.
+    if (def.audit === true) trace.input = await parsedOrNothing(def.input, raw);
+    throw denial;
+  }
   const input = await validateInput(def.input, raw, name);
   trace.input = input;
   // The one place a row-level rule gets its row. Once per invocation, never per row:
@@ -224,11 +236,7 @@ async function perform(
   // action with no loader hands the rule `null` — unchanged, and never a silent allow,
   // because a rule that reads `row` has to decide what `null` means.
   const row = def.row === undefined ? null : ((await def.row({ input, ctx })) ?? null);
-  guard(
-    def.policy,
-    { actor: actorOf(ctx), input, row, ctx, action: name },
-    options.surface ?? 'server',
-  );
+  guard(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
 
   // Output parsing sits inside `run` so a replayed idempotent response is the parsed value too —
   // one shape on the wire, first call and every retry. No span of its own: `execute` above holds

package/src/policy-gate.ts

@@ -9,6 +9,7 @@ import { assertNever, isAnonymous } from '@ultimat3/core';
 import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
 import {
   enforce,
+  enforceBeforeInput,
   policyPermissions as flattenedPermissions,
   admitsAnonymous as policyAdmitsAnonymous,
 } from '@ultimat3/policy';
@@ -56,6 +57,25 @@ export function guard(policy: ActionPolicy, subject: PolicySubject, surface: Sur
   if (denial !== undefined) throw new ActionDeniedError(subject.action, denial);
 }
 
+/**
+ * The actor-only half of `guard`, run BEFORE the input is parsed: a caller the policy refuses
+ * whatever they send gets the 403 (or 401) here, and never the 400 whose issue list describes
+ * the input schema of an operation they may not call. Undecided — a predicate that reads the input
+ * or the row — passes, and `guard` decides after the parse exactly as before. Same denial class,
+ * same code, same surface rendering as `guard`'s.
+ */
+export function guardBeforeInput(
+  policy: ActionPolicy,
+  subject: Omit<PolicySubject, 'input' | 'row'>,
+  surface: Surface,
+): void {
+  const denial = enforceBeforeInput(policySurface(surface), policy, {
+    actor: subject.actor,
+    ctx: subject.ctx,
+  });
+  if (denial !== undefined) throw new ActionDeniedError(subject.action, denial);
+}
+
 /** A direct server call is the job surface: no request, no response to shape. */
 function policySurface(surface: Surface): PolicySurface {
   switch (surface) {

package/src/validate.ts

@@ -31,6 +31,16 @@ export async function validateInput<S extends StandardSchemaV1>(
   return result.value;
 }
 
+/**
+ * The parse without the refusal: the value, or `undefined` when it does not parse. Only for a
+ * record of an attempt already refused on other grounds (`invoke`'s audit of a before-input
+ * denial) — never on a path that goes on to run anything.
+ */
+export async function parsedOrNothing(schema: StandardSchemaV1, raw: unknown): Promise<unknown> {
+  const result = await validateAsync(schema, raw);
+  return result.issues === undefined ? result.value : undefined;
+}
+
 /**
  * The handler's return value is data too. Parsing it is what makes the OpenAPI
  * response schema, the typed client and the MCP `outputSchema` true rather than