@ultimat3/action 30.9.0 → 31.0.0

package/src/invoke.ts

@@ -16,10 +16,12 @@ import {
   anonymousActor,
   ctxOf,
   failureCaptureActive,
+  instrument,
   isUltimateError,
   REDACTED,
   recordFailureInput,
   runWithContext,
+  subscribed,
   tryUseContext,
   useContext,
   withChildContext,
@@ -29,6 +31,7 @@ import {
 import { statusFor } from '@ultimat3/http';
 import { maskSensitive } from '@ultimat3/schema';
 import type { AnyAction, AnyActionDef, InvokeOptions } from './action';
+import { declarationOf, drainsItsHandler } from './action-stream';
 import type { AuditRecord } from './audit';
 import {
   auditFailureFor,
@@ -40,6 +43,8 @@ import {
 import { bustAfterCommit } from './cache-gate';
 import { judgedHandler } from './declared-errors';
 import { ActionForeignError, ActionUnregisteredError } from './errors';
+import type { HandlerOverride } from './handler-override';
+import { handlerOverrideOf, setHandlerOverride } from './handler-override';
 import { getIdempotencyStore, withIdempotency } from './idempotency';
 import { idempotencyKeyFor } from './idempotency-key';
 import { drawMeter } from './meter-gate';
@@ -83,6 +88,15 @@ export function handlerReached(target: AnyAction): number {
   return HANDLER_REACHED.get(defOf(target)) ?? 0;
 }
 
+/**
+ * A test double where `target`'s `handle` is, on every surface — policy, rate limit, input parse,
+ * meter, idempotency and output parse still run. `undefined` restores the declared handler. On
+ * `@ultimat3/action/adapter` only: `@ultimat3/testing`'s `stub()` is its caller.
+ */
+export function overrideHandler(target: AnyAction, handle: HandlerOverride | undefined): void {
+  setHandlerOverride(declarationOf(defOf(target)), handle);
+}
+
 /** Projections need a stable name; an unregistered action has none yet. */
 export function actionName(target: AnyAction): string {
   if (target.name.length === 0) throw new ActionUnregisteredError();
@@ -233,8 +247,13 @@ async function traced(
       'ultimate.actor.kind': ctx.actor.kind,
       'ultimate.idempotent': def.idempotent === true,
     });
+    const startedAt = performance.now();
     try {
       const value = await perform(def, name, raw, ctx, options, trace);
+      // Every invocation, sampled or not — the span reaches an exporter only when sampled.
+      if (subscribed('action.invoke')) {
+        instrument('action.invoke', { action: name, durationMs: performance.now() - startedAt });
+      }
       span.setAttributes({
         'ultimate.outcome': 'allowed',
         'ultimate.idempotency.replayed': trace.replayed,
@@ -248,6 +267,13 @@ async function traced(
       // are different questions, and a trace that called both "error" cannot separate them.
       span.setAttribute('ultimate.outcome', auditOutcomeFor(error));
       if (isUltimateError(error)) span.setAttribute('ultimate.error.code', error.code);
+      if (subscribed('action.invoke')) {
+        instrument('action.invoke', {
+          action: name,
+          durationMs: performance.now() - startedAt,
+          error,
+        });
+      }
       throw error;
     }
   });
@@ -345,7 +371,9 @@ async function perform(
     HANDLER_REACHED.set(def, (HANDLER_REACHED.get(def) ?? 0) + 1);
     // Read here, not closed over: under a key this runs in `runToCompletion`'s scope, and a handler
     // passing the outer `ctx.signal` onward would fail its vendor call and settle a failure.
-    const produced = await judgedHandler(def, name, () => def.handle({ input, ctx: useContext() }));
+    const override = drainsItsHandler(def) ? undefined : handlerOverrideOf(def);
+    const handle = override ?? def.handle.bind(def);
+    const produced = await judgedHandler(def, name, () => handle({ input, ctx: useContext() }));
     return validateOutput(def.output, produced, name);
   };
   // The meter is drawn LAST before the handler, on every surface `surface: 'server'` included: a

package/src/loader.ts

@@ -0,0 +1,5 @@
+// `@ultimat3/action/loader` — where an export is NAMED as an action: `x`'s module scan and the
+// framework's own fixtures. Never the `.` barrel: an app hands its modules to `defineApi`, the one
+// registration path (axiom 1), and that reaches these through the same registry.
+
+export { registerAction, registerActions } from './registry';

package/src/meter-store.ts

@@ -4,6 +4,7 @@
  * the pool it opened, so a tenant's day is one counter across every replica and every restart.
  */
 
+import { adapterSlot } from '@ultimat3/core/adapter';
 import { memoryMeterStore } from './meter-memory';
 
 /** One counter: whose, which meter, which period declaration. */
@@ -45,17 +46,24 @@ export interface MeterStore {
   releaseWarning(key: MeterKey, periodStartMs: number): Promise<void>;
 }
 
-let installed: MeterStore = memoryMeterStore();
+let base: MeterStore = memoryMeterStore();
+/** The installed store: a stack over the process default, released in any order. */
+const slot = adapterSlot<MeterStore>(() => base);
 
-export function setMeterStore(store: MeterStore): void {
-  installed = store;
+/**
+ * The boot's installer (its release removes THIS install only, in any order — `adapterSlot`), on `@ultimat3/action/adapter` and never the `.` barrel: an app swaps the
+ * store with `meterStore:` in `apps/<app>/runtime.ts`.
+ */
+export function installMeterStore(store: MeterStore): () => void {
+  return slot.install(store);
 }
 
 export function getMeterStore(): MeterStore {
-  return installed;
+  return slot.current();
 }
 
 /** Back to a fresh process default. The boot's teardown, and a test's. */
 export function resetMeterStore(): void {
-  installed = memoryMeterStore();
+  slot.reset();
+  base = memoryMeterStore();
 }

package/src/openapi.ts

@@ -145,6 +145,8 @@ const PROBLEM_SCHEMA: JsonSchemaObject = {
         },
       },
     },
+    // Present, and only ever `true`, when validation stopped at `MAX_ISSUES`: `issues` is a prefix.
+    issuesTruncated: { type: 'boolean', enum: [true] },
     // Only the keys the code declared through `registerProblemMeta`; its shape is per code.
     meta: { type: 'object' },
   },

package/src/policy-gate.ts

@@ -1,87 +1,52 @@
 /**
- * The single point of contact with @ultimat3/policy. Every surface (HTTP, MCP,
- * job, direct server call) reaches authz through `guardAction()` — there is no second
- * code path, which is what makes "one authz system" true rather than aspirational.
+ * The single point of contact with @ultimat3/policy. Every surface (HTTP, MCP, job, direct server
+ * call) reaches authz here, through policy's `guardPrimitive` — the one gate `@ultimat3/query`
+ * runs too, so the two primitives cannot drift on a surface rule.
  */
 
 import type { Actor, Ctx } from '@ultimat3/core';
-import { assertNever } from '@ultimat3/core';
-import type { Policy, Surface as PolicySurface } from '@ultimat3/policy';
-import { enforce, enforceBeforeInput } from '@ultimat3/policy';
+import type { GuardSubject, Policy, PrimitiveSurface } from '@ultimat3/policy';
+import { guardPrimitive } from '@ultimat3/policy';
 import { ActionDeniedError } from './errors';
 
-/**
- * Policies are opaque here: we evaluate them, we never introspect their rules.
- * `TRow` is what a row-level rule decides about, defaulted so the bare
- * `ActionPolicy` keeps meaning "decides on input, any row or none".
- */
+/** Opaque here: evaluated, never introspected. `TRow` is what a row-level rule decides about. */
 export type ActionPolicy<TRow = unknown> = Policy<unknown, TRow>;
 
 /** Which projection is running. Selects the deny renderer, never the decision. */
-export type Surface = 'server' | 'http' | 'mcp' | 'job';
+export type Surface = PrimitiveSurface<'action'>;
 
 export interface PolicySubject {
   readonly actor: Actor | null;
   readonly input: unknown;
-  /**
-   * The already-loaded row a row-level rule decides about; `null` when the action
-   * declared no loader. Optional here and required in `PolicyArgs` for the same
-   * reason `EvaluateArgs.row` is: a surface deciding on input alone should not have
-   * to write `row: null`, but the predicate it reaches must still see the field.
-   * `invoke` always passes it, so the gap closes before any rule runs.
-   */
+  /** The loaded row a row-level rule decides about; `invoke` always passes it, `null` for none. */
   readonly row?: unknown;
   readonly ctx: Ctx;
   readonly action: string;
 }
 
-/**
- * Evaluate once, render the denial per surface. `enforce` runs the same policy
- * object for every surface, so an actor denied over HTTP is denied over MCP with
- * the same reason and the same code.
- */
+/** Evaluate once, render the denial per surface: one reason and one code on every surface. */
 export function guardAction(policy: ActionPolicy, subject: PolicySubject, surface: Surface): void {
-  const denial = enforce(policySurface(surface), policy, {
-    input: subject.input,
-    actor: subject.actor,
-    // `evaluate()` normalises a missing row to `null`, so an input-only rule and a
-    // row rule reach the predicate through one shape rather than two.
-    row: subject.row,
-    ctx: subject.ctx,
-  });
-  if (denial !== undefined) throw new ActionDeniedError(subject.action, denial);
+  const { action: name, ...rest } = subject;
+  guard(policy, { stage: 'input', name, ...rest }, surface);
 }
 
 /**
- * The actor-only half of `guardAction`, 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 `guardAction` decides after the parse exactly as before. Same denial
- * class, same code, same surface rendering as `guardAction`'s.
+ * The actor-only half, BEFORE the input parse: a caller refused whatever they send gets the 403
+ * (or 401), never a 400 describing an input schema they may not call. Undecided passes.
  */
 export function guardActionBeforeInput(
   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);
+  guard(
+    policy,
+    { stage: 'actor', name: subject.action, actor: subject.actor, ctx: subject.ctx },
+    surface,
+  );
 }
 
-/** A direct server call is the job surface: no request, no response to shape. */
-function policySurface(surface: Surface): PolicySurface {
-  switch (surface) {
-    case 'http':
-      return 'http';
-    case 'mcp':
-      return 'mcp';
-    case 'job':
-    case 'server':
-      return 'job';
-    default:
-      return assertNever(surface);
-  }
+function guard(policy: ActionPolicy, subject: GuardSubject, surface: Surface): void {
+  const refused = guardPrimitive('action', policy, subject, surface);
+  if (refused !== undefined) throw new ActionDeniedError(refused);
 }

package/src/rate-limit-gate.ts

@@ -5,7 +5,14 @@
  */
 
 import type { Ctx } from '@ultimat3/core';
-import { asyncContext, isAnonymous } from '@ultimat3/core';
+import {
+  asyncContext,
+  fixedRateLimitOf,
+  rateLimitScopeOf,
+  rateLimitSpendsOn,
+  rateLimitSubjectOf,
+  resolvedRateLimitOf,
+} from '@ultimat3/core';
 import type { RateLimitDecision } from '@ultimat3/http';
 // The bucket maths, the subject precedence and the refusal are all `@ultimat3/http`'s (tier 2):
 // a copy here would be a second answer to "what does this limit mean" and "whose bucket is it".
@@ -56,13 +63,6 @@ export function inJobFrame(): boolean {
   return callerFrame.get()?.job === true;
 }
 
-/**
- * Namespaced, never the bare action name: the HTTP pipeline still spends its `default` bucket
- * under `<route name>|<subject>`, and one key taken against two bucket shapes in one store would
- * corrupt both counters.
- */
-const ACTION_SCOPE = 'action';
-
 export interface RateLimitSpendOptions {
   readonly surface: Surface;
   /** The connection address — the only subject an anonymous caller has. */
@@ -86,20 +86,20 @@ export async function spendActionLimit(
   ctx: Ctx,
   options: RateLimitSpendOptions,
 ): Promise<void> {
-  if (limit === undefined || options.surface === 'server') return;
+  if (limit === undefined || !rateLimitSpendsOn(options.surface)) return;
   const frame = callerFrame.get();
   // A job run, or any call nested inside one (an `agent()` run as a job calling its tools as
   // `'mcp'`): never a visitor's address, and the unattributed bucket rather than `ip:unknown`.
   const inJob = options.surface === 'job' || inJobFrame();
   const spends = rateLimitSpends(
     {
-      actorId: isAnonymous(ctx.actor) ? null : ctx.actor.id,
-      // Read off an anonymous actor too: a job run IS the worker's anonymous identity carrying the
-      // job's org (`jobRunActor`), and that org is who the run is — charging every tenant's runs
-      // to one `ip:unknown` key let one tenant's backlog refuse everyone's.
-      orgId: ctx.actor.orgId ?? null,
-      ip: options.clientAddress ?? (inJob ? null : (frame?.address ?? null)),
-      routeName: `${ACTION_SCOPE}:${name}`,
+      // Core's one subject rule — the org is read off an anonymous actor too (a job run).
+      ...rateLimitSubjectOf(
+        ctx.actor,
+        options.clientAddress ?? (inJob ? null : (frame?.address ?? null)),
+      ),
+      // Namespaced, never the bare name: the HTTP pipeline spends `<route name>|<subject>`.
+      routeName: rateLimitScopeOf('action', name),
       ...(inJob ? { unattributed: UNATTRIBUTED_JOB } : {}),
     },
     // The tenant allowance is the HTTP pipeline's (it spends it for every route, a handler-limited
@@ -109,7 +109,7 @@ export async function spendActionLimit(
   // Resolved once per call, BEFORE any bucket is touched, and through `toBucket`'s own screen: a
   // resolver answering `NaN`, `0` or `Infinity` is `X_RATE_LIMIT_INVALID`, never allow-all.
   const bucket = toBucket(name, {
-    limit: await resolvedRateLimit(limit, ctx),
+    limit: await resolvedRateLimitOf(limit, { ctx }),
     windowMs: limit.windowMs,
   });
   for (const spend of spends) {
@@ -124,16 +124,6 @@ export async function spendActionLimit(
   }
 }
 
-/**
- * The number a call is held to: the declared one, or what the resolver answers from `ctx` — the
- * tenant's plan, read by the app. A non-number becomes `NaN`, so `toBucket` refuses it by name.
- */
-async function resolvedRateLimit(limit: ActionRateLimit, ctx: Ctx): Promise<number> {
-  const resolved: unknown =
-    typeof limit.limit === 'function' ? await limit.limit({ ctx }) : limit.limit;
-  return typeof resolved === 'number' ? resolved : Number.NaN;
-}
-
 /**
  * At mount, never on the first request: a fixed pair is checked whole; a per-call limit has only
  * its window to check until a caller resolves it, so the window is checked against one request.
@@ -149,6 +139,5 @@ export function assertActionRateLimit(name: string, limit: ActionRateLimit): voi
 export function fixedRateLimit(
   limit: ActionRateLimit | undefined,
 ): { readonly limit: number; readonly windowMs: number } | null {
-  if (limit === undefined || typeof limit.limit === 'function') return null;
-  return { limit: limit.limit, windowMs: limit.windowMs };
+  return fixedRateLimitOf(limit);
 }

package/src/validate.ts

@@ -26,7 +26,15 @@ export async function parseActionInput<S extends StandardSchemaV1>(
   const result = await validateAsync(schema, raw);
   if (result.issues !== undefined) {
     const issues = toValidationIssues(result.issues);
-    throw new InputInvalidError(actionName, formatIssues(issues).join('; '), issues);
+    // `issuesTruncated`: validation stopped at `MAX_ISSUES`, and the refusal must say the list is
+    // a prefix rather than let a client render 100 rejections as the whole answer.
+    throw new InputInvalidError(
+      actionName,
+      formatIssues(issues).join('; '),
+      issues,
+      'action',
+      result.issuesTruncated === true,
+    );
   }
   return result.value;
 }

package/src/wire-issues.ts

@@ -5,24 +5,22 @@
  * structure another layer will render.
  */
 
-import { stringField } from '@ultimat3/core';
+import { stringField } from '@ultimat3/core/page';
 import type { ValidationIssue } from '@ultimat3/schema';
-import { issueRuleFacts } from '@ultimat3/schema';
-
-/**
- * A list this long is not a form's worth of rejections; it is a body meant to be expensive. The
- * entries are rendered into a DOM by whoever displays them, so the bound is here rather than there.
- */
-export const MAX_WIRE_ISSUES = 100;
+import { issueRuleFacts, MAX_ISSUES } from '@ultimat3/schema';
 
 /**
+ * Bounded by `@ultimat3/schema`'s `MAX_ISSUES`, imported and never restated or re-exported: a list
+ * longer is not a form's worth of rejections but a body meant to be expensive, and the server stops
+ * validating at exactly that length, so a capped list arrives whole.
+ *
  * All-or-nothing on purpose. A partly-parsed list would DROP the entries it could not read, and
  * nothing downstream would know: a caller that finds `meta.issues` uses it INSTEAD of the
  * flattened `cause`, so a dropped entry is a rejection the user never hears about. Refusing the
  * whole list leaves the `cause` — which still holds every issue — as the answer.
  */
 export function issuesFromWire(value: unknown): readonly ValidationIssue[] | undefined {
-  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_WIRE_ISSUES) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_ISSUES) {
     return undefined;
   }
   const issues: ValidationIssue[] = [];