@ultimat3/action 29.4.0 → 30.1.0

package/src/idempotency.ts

@@ -4,15 +4,29 @@
  * a value or a failure — and a concurrent duplicate is refused rather than run twice, because a
  * double charge is worse than a 409.
  */
-import { compareFingerprint, isUltimateError, keyedFingerprint, logger } from '@ultimat3/core';
+import {
+  compareFingerprint,
+  finiteCount,
+  isUltimateError,
+  jsonbRefusal,
+  keyedFingerprint,
+  logger,
+  MAX_TIMER_MS,
+  runToCompletion,
+  tryUseContext,
+} from '@ultimat3/core';
 import {
   IdempotencyConflictError,
   IdempotencyNotSharedError,
+  IdempotencyOutputUnserializableError,
   IdempotencyReplayedFailureError,
+  IdempotencyRunCeilingError,
   IdempotentReplayRedactedError,
 } from './errors';
 import { memoryIdempotencyStore } from './idempotency-memory';
 import { restingAnswer } from './idempotency-redact';
+import { requestDeadlineMs } from './request-deadline';
+import { carrySettleOnCommit } from './tx-scope';
 
 /**
  * Where a store's records live. Declared by the driver, never inferred — the same rule
@@ -153,6 +167,8 @@ export interface IdempotencyStore {
  */
 export interface IdempotencyConfig {
   readonly scope: IdempotencyScope;
+  /** How long a keyed run may go on, in ms. Default `idempotencyCeilingMs()`. */
+  readonly ceilingMs?: number | undefined;
 }
 
 /**
@@ -166,6 +182,10 @@ let defaultStore: IdempotencyStore = memoryIdempotencyStore();
 
 /** Declared at boot, before `registerActions()`. Nothing infers a replica count. */
 export function configureIdempotency(next: IdempotencyConfig): void {
+  // At boot: unscreened, a bad value is refused by every keyed request instead.
+  if (next.ceilingMs !== undefined) {
+    finiteCount('configureIdempotency', 'ceilingMs', next.ceilingMs, 1);
+  }
   config = next;
 }
 
@@ -173,6 +193,21 @@ export function idempotencyConfig(): IdempotencyConfig {
   return config;
 }
 
+/** The ceiling when the request deadline is `0`, "no deadline": there is nothing to double. */
+const CEILING_WITHOUT_DEADLINE_MS = 60_000;
+
+/**
+ * The hard ceiling on a keyed run: the declared one, else twice the request deadline (60 s by
+ * default). A handler the deadline's own socket answer has given up on gets as long again to finish;
+ * read per call because the app declares its deadline after the boot built its stores.
+ */
+export function idempotencyCeilingMs(): number {
+  if (config.ceilingMs !== undefined) return config.ceilingMs;
+  const deadline = requestDeadlineMs();
+  // `ceil`: http's screen admits a fraction, and this one counts whole milliseconds.
+  return deadline > 0 ? Math.ceil(2 * deadline) : CEILING_WITHOUT_DEADLINE_MS;
+}
+
 export function setIdempotencyStore(store: IdempotencyStore): void {
   defaultStore = store;
 }
@@ -216,7 +251,7 @@ export interface IdempotentOutcome<T> {
  * X_IDEMPOTENCY_CONFLICT for a payload mismatch, X_IDEMPOTENCY_CONFLICT for a duplicate still in
  * flight.
  *
- * **Everything `run()` throws is treated as possibly-committed.** `guardAction()` and `validateInput`
+ * **Everything `run()` throws is treated as possibly-committed.** `guardAction()` and `parseActionInput`
  * both run before this gate is reached (`invoke.ts`), so by the time `run` is called the only
  * things left are the handler and `validateOutput` — and the second of those throws *after* the
  * first has committed. Releasing the reservation there is what turned a rounding change in an
@@ -232,6 +267,8 @@ export interface WithIdempotencyOptions {
    * the key's outcome, and a retry once the bucket refills must still be able to run.
    */
   readonly beforeRun?: () => Promise<void>;
+  /** This call's ceiling, in ms, over `idempotencyCeilingMs()`. Past it the failure is settled. */
+  readonly ceilingMs?: number | undefined;
 }
 
 export async function withIdempotency<T>(
@@ -241,6 +278,12 @@ export async function withIdempotency<T>(
   run: () => Promise<T>,
   options: WithIdempotencyOptions = {},
 ): Promise<IdempotentOutcome<T>> {
+  const ceilingMs = finiteCount(
+    'withIdempotency',
+    'ceilingMs',
+    options.ceilingMs ?? idempotencyCeilingMs(),
+    1,
+  );
   const requestHash = keyedFingerprint(input, IDEMPOTENCY_FINGERPRINT_PURPOSE);
   const { record, created } = await store.reserve(key, requestHash);
   if (record.requestHash !== requestHash) assertSamePayload(key, record.requestHash, input);
@@ -269,9 +312,15 @@ export async function withIdempotency<T>(
       throw error;
     }
   }
+  // A run under a key is OWED its end: the orphan finishing is what makes the replay answer success.
+  // An aborted `ctx.signal` would fail its vendor call, `settleFailure` would run, and the key would
+  // replay a failure. The COMMIT of a transaction around this gate sits outside the scope below, so
+  // that root is marked too, and the settle rides it. A reclaimed reservation still fences its own.
+  // The escape removes every bound the request had, so the ceiling below is the one it has.
+  carrySettleOnCommit();
   let value: T;
   try {
-    value = await run();
+    value = await runWithinCeiling(key, ceilingMs, run);
   } catch (error) {
     await settleFailure(store, key, record.id, error);
     throw error;
@@ -290,10 +339,66 @@ export async function withIdempotency<T>(
   // The CALLER gets `value` whole; the store gets the resting copy, so an answer carrying a
   // credential is never written down in plaintext for the window (#591).
   const resting = restingAnswer(value);
+  if (!jsonRepresentable(resting.value)) {
+    const refusal = new IdempotencyOutputUnserializableError(key);
+    await settleFailure(store, key, record.id, refusal);
+    throw refusal;
+  }
   await store.settle(key, resting.value, record.id, resting.redacted);
   return { value, replayed: false };
 }
 
+/**
+ * Whether a store can write this down. Tested HERE so both stores answer alike: memory holds any
+ * value, and Postgres throws from its own `JSON.stringify`. A resting copy has no `toJSON` left to
+ * run, so this calls no app code. `undefined` passes and rests as `null` (JSON has no `undefined`):
+ * the replay goes through the action's `output` schema, and that schema answers for its shape.
+ * Text `jsonb` refuses counts too: Postgres alone would raise it, after the handler ran.
+ */
+function jsonRepresentable(value: unknown): boolean {
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined || jsonbRefusal(text) === undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * `run` in `runToCompletion`'s scope, under a signal this ceiling aborts. ABORTS before it rejects,
+ * as a job's step timeout does: the failure about to be settled is what a retry replays, so a handler
+ * still going must be told. One that ignores it is let go of: the in-flight count and the drain stop
+ * waiting, and a transaction around the gate rolls back on this throw, so its statements then refuse.
+ */
+function runWithinCeiling<T>(key: string, ceilingMs: number, run: () => Promise<T>): Promise<T> {
+  const ceiling = new AbortController();
+  const startedAt = tryUseContext()?.now().getTime();
+  const bound = {
+    signal: ceiling.signal,
+    ...(startedAt === undefined ? {} : { deadlineAt: startedAt + ceilingMs }),
+  };
+  // Past what a timer holds `setTimeout` arms ~1 ms, and the longest ceiling killed every handler.
+  const delayMs = Math.min(ceilingMs, MAX_TIMER_MS);
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const failure = new IdempotencyRunCeilingError(key, ceilingMs);
+      ceiling.abort(failure);
+      reject(failure);
+    }, delayMs);
+    // `async`: a `run` that throws synchronously takes the same path, and clears the timer.
+    (async () => runToCompletion(run, bound))().then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (cause: unknown) => {
+        clearTimeout(timer);
+        reject(cause);
+      },
+    );
+  });
+}
+
 /**
  * A stored fingerprint that is not this request's exact string. A legacy unkeyed one (a row
  * written before keying) is still checked exactly. One keyed under a secret this process does not

package/src/index.ts

@@ -31,12 +31,16 @@ export type {
   ActionHandlerArgs,
   ActionMcp,
   ActionRateLimit,
+  ActionRateLimitFact,
   ActionRowArgs,
   AnyAction,
   InvokeOptions,
   McpDescriptorMeta,
+  StreamAction,
+  StreamActionDef,
 } from './action';
 export { action, describeAction, isAction } from './action';
+export { chunksRead } from './action-stream';
 /**
  * The app's API as a whole — `defineApi({ http: { pathStyle, mounts }, openapi })` — read back by
  * the boot (bearer mounts) and `x manifest` (the complete and per-mount documents).
@@ -67,6 +71,12 @@ export { DEFAULT_MAX_AUDIT_RECORDS, memoryAuditSink } from './audit-memory';
  */
 export type { PostgresAuditSink, PostgresAuditSinkOptions } from './audit-postgres';
 export { postgresAuditSink, SQL_AUDIT_TABLE } from './audit-postgres';
+export type {
+  AuditSubjectRef,
+  AuditSubjectTarget,
+  AuditSubjectTargetOptions,
+} from './audit-subject-target';
+export { AUDIT_SUBJECT_COLUMNS, auditSubjectTarget } from './audit-subject-target';
 export type {
   ActionLike,
   ActionMap,
@@ -75,6 +85,7 @@ export type {
   ClientMethod,
   ClientOptions,
   FetchLike,
+  StreamClientMethod,
 } from './client';
 export { rpc } from './client';
 export type { ContractTest, ContractTestOptions } from './contract-test';
@@ -96,8 +107,10 @@ export {
   IdempotencyConflictError,
   IdempotencyKeyInvalidError,
   IdempotencyNotSharedError,
+  IdempotencyOutputUnserializableError,
   IdempotencyReplayedFailureError,
   IdempotencyReservationLostError,
+  IdempotencyRunCeilingError,
   IdempotencyStatusUnknownError,
   IdempotentReplayRedactedError,
   InputInvalidError,
@@ -107,21 +120,37 @@ export {
   RpcFailedError,
 } from './errors';
 export {
+  ActionDeprecationSuccessorInvalidError,
   ActionHttpPathInvalidError,
   ActionPathStyleInvalidError,
   OpenApiConfigInvalidError,
 } from './errors-http';
+export type { MeterExceededInput, MeterField } from './errors-meter';
+export { MeterExceededError, MeterInvalidError } from './errors-meter';
+export { ActionStreamInvalidError } from './errors-stream';
+export type {
+  ExerciseActorOptions,
+  ExerciseOffOptions,
+  ExerciseOptions,
+  ExerciseReport,
+} from './exercise';
+export { exerciseAction } from './exercise';
 export type { OpenApiOperation } from './http';
 export {
   operationTagOf,
-  REPLAYED_HEADER,
   toOpenApiOperation,
   toPostBinding,
   toRoute,
 } from './http';
 /** `http: { path }` on an action pins its URL; the app's `pathStyle` derives every other one. */
-export type { ActionHttp } from './http-path';
-export { actionPathStyle, forgetHandedOutActionPaths } from './http-path';
+export type { ActionHttp, ActionHttpMethod } from './http-path';
+export {
+  ACTION_HTTP_METHODS,
+  actionHttpPinOf,
+  actionPathStyle,
+  forgetHandedOutActionPaths,
+} from './http-path';
+export { EVENT_STREAM } from './http-stream';
 /**
  * The idempotency seam. `withIdempotency` and `IDEMPOTENCY_HEADER` are both public, so a plain
  * mutating `route` can reserve-and-replay exactly as an action does — `idempotencyKeyFor` is the
@@ -144,6 +173,7 @@ export {
   DEFAULT_IDEMPOTENCY_CONFIG,
   getIdempotencyStore,
   IDEMPOTENCY_STATUSES,
+  idempotencyCeilingMs,
   idempotencyConfig,
   isIdempotencyStatus,
   resetIdempotency,
@@ -172,6 +202,27 @@ export type { ActionJobHandle } from './job-handle';
 export { toJobHandle } from './job-handle';
 export type { JsonSchemaObject } from './json-schema';
 export { jsonSchemaOf } from './json-schema';
+/**
+ * The meter seam: `meter: { name, period, limit, warnAt, onWarn }` on an action, drawn inside
+ * `invoke` on every surface. The draw itself (`meter-gate.ts`) stays unexported — one caller.
+ * `MeterWarning` is the schema an app's warning `job()` declares as its input.
+ */
+export type {
+  ActionMeter,
+  ActionMeterFact,
+  MeterLimitArgs,
+  MeterPeriod,
+  MeterWarnEnqueueOptions,
+  MeterWarnTarget,
+  ResolvedLimit,
+} from './meter';
+export { METER_PERIODS, MeterWarning } from './meter';
+export type { MemoryMeterStoreOptions } from './meter-memory';
+export { DEFAULT_MAX_METER_KEYS, memoryMeterStore } from './meter-memory';
+export type { PostgresMeterStoreOptions } from './meter-postgres';
+export { postgresMeterStore, SQL_METER_TABLE } from './meter-postgres';
+export type { MeterDraw, MeterDrawResult, MeterKey, MeterStore } from './meter-store';
+export { getMeterStore, resetMeterStore, setMeterStore } from './meter-store';
 export type {
   LocalTable,
   LocalTableName,
@@ -216,6 +267,20 @@ export {
   resetActions,
 } from './registry';
 export { requestDeadlineMs } from './request-deadline';
+/**
+ * What a named tool passes on its way to `invoke`, on either tool surface. `@ultimat3/mcp`'s
+ * `mcpConfirmations` registers one and `@ultimat3/ai`'s adapter reads it: one tier down from both.
+ */
+export type { ToolGate, ToolGateCall } from './tool-gate';
+export {
+  admitActionCaller,
+  asCallerContext,
+  gatedToolNames,
+  knownToolNames,
+  noteToolNames,
+  registerToolGate,
+  toolGateFor,
+} from './tool-gate';
 /**
  * A mutator FACTORY, never a ninth primitive: `transition()` returns a `mutator`, so a move through
  * a state machine inherits the route, the OpenAPI operation, the typed client, the MCP tool, the job
@@ -229,6 +294,12 @@ export type {
   TransitionValues,
 } from './transition';
 export { transition } from './transition';
+/**
+ * `invoke`'s input parse and its `X_INPUT_INVALID` refusal, alone. Exported so a caller that must
+ * hold something else to an action's input — an agent eval's tool double (`@ultimat3/ai`) — runs
+ * this one check instead of a copy that drifts.
+ */
+export { parseActionInput } from './validate';
 /**
  * The one reader of a problem document's `issues` member. Exported because the typed client is not
  * the only caller that meets one: an island that posts with a plain `fetch` — which is what

package/src/invoke.ts

@@ -1,6 +1,6 @@
 /**
  * The one invocation core: ask who is calling, spend the rate limit, parse input, evaluate
- * policy, run the handler, parse output. The declaration lives in this module's private store, so `handle` is
+ * policy, draw the meter, run the handler, parse output. The declaration lives in this module's private store, so `handle` is
  * unreachable from anywhere else — HTTP, MCP, jobs and `.as()` hand `invoke` a
  * payload, and none of them can become a second execution path.
  *
@@ -15,13 +15,19 @@ import {
   actorOf,
   anonymousActor,
   ctxOf,
+  failureCaptureActive,
   isUltimateError,
+  REDACTED,
+  recordFailureInput,
   runWithContext,
   tryUseContext,
   useContext,
   withChildContext,
+  withFailureCapture,
   withSpan,
 } from '@ultimat3/core';
+import { statusFor } from '@ultimat3/http';
+import { maskSensitive } from '@ultimat3/schema';
 import type { AnyAction, AnyActionDef, InvokeOptions } from './action';
 import type { AuditRecord } from './audit';
 import {
@@ -32,12 +38,14 @@ import {
   auditThrew,
 } from './audit-gate';
 import { bustAfterCommit } from './cache-gate';
+import { judgedHandler } from './declared-errors';
 import { ActionForeignError, ActionUnregisteredError } from './errors';
 import { getIdempotencyStore, withIdempotency } from './idempotency';
 import { idempotencyKeyFor } from './idempotency-key';
+import { drawMeter } from './meter-gate';
 import { guardAction, guardActionBeforeInput } from './policy-gate';
 import { spendActionLimit, withCallerAddress, withJobFrame } from './rate-limit-gate';
-import { parsedOrNothing, validateInput, validateOutput } from './validate';
+import { parseActionInput, parsedOrNothing, validateOutput } from './validate';
 
 /**
  * Private on purpose. `@ultimat3/action` exports no way to read this back, which
@@ -63,6 +71,18 @@ export function defOf(target: AnyAction): AnyActionDef {
   return def;
 }
 
+/**
+ * How many times each declaration's `handle` has started, keyed like `DECLARATIONS`. Read only by
+ * `exercise.ts` — never re-exported — so "zero runs reached the handler" is countable without a
+ * second execution path: a contract that never got past policy or parse is its own red.
+ */
+const HANDLER_REACHED = new WeakMap<AnyActionDef, number>();
+
+/** Starts of `target`'s handler so far, across every surface. Off the barrel on purpose. */
+export function handlerReached(target: AnyAction): number {
+  return HANDLER_REACHED.get(defOf(target)) ?? 0;
+}
+
 /** 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();
@@ -190,6 +210,20 @@ async function execute(
   ctx: Ctx,
   options: InvokeOptions,
   trace: InvokeTrace,
+): Promise<unknown> {
+  // A 5xx keeps a replayable bundle when `failureCapture` is on (`x repro`); off, `run` runs bare.
+  return withFailureCapture('action', name, statusFor, () =>
+    traced(def, name, raw, ctx, options, trace),
+  );
+}
+
+async function traced(
+  def: AnyActionDef,
+  name: string,
+  raw: unknown,
+  ctx: Ctx,
+  options: InvokeOptions,
+  trace: InvokeTrace,
 ): Promise<unknown> {
   return withSpan(`action.${name}`, async (span) => {
     span.setAttributes({
@@ -237,7 +271,9 @@ async function perform(
   } 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);
+    if (def.audit === true) {
+      trace.input = maskSensitive(def.input, await parsedOrNothing(def.input, raw), REDACTED);
+    }
     throw denial;
   }
   // The ONE place a declared `rateLimit:` is spent, so every surface draws on the same bucket.
@@ -260,15 +296,21 @@ async function perform(
   // committed write had not happened. A key the store already holds is a replay (or a duplicate in
   // flight, answered 409); only a key it does not hold spends here. The peek can be stale both
   // ways, so `withIdempotency` meters a reservation it CREATED that this peek did not pay for.
-  const spentEarly =
+  // The same peek serves the row rule below, so an action that needs neither makes no read here.
+  const peeked =
     trace.idempotencyKey === null ||
     store === undefined ||
-    def.rateLimit === undefined ||
-    (await store.get(trace.idempotencyKey)) === undefined;
+    (def.rateLimit === undefined && def.row === undefined)
+      ? undefined
+      : await store.get(trace.idempotencyKey);
+  const spentEarly = def.rateLimit === undefined || peeked === undefined;
   if (spentEarly) await spend();
 
-  const input = await validateInput(def.input, raw, name);
-  trace.input = input;
+  const input = await parseActionInput(def.input, raw, name);
+  if (failureCaptureActive()) recordFailureInput(maskSensitive(def.input, input, REDACTED));
+  // The audit record's copy, `.sensitive()` fields masked by THIS action's own schema — never a
+  // key table, so a `cardPan` flagged here changes nothing another action records or stores.
+  if (def.audit === true) trace.input = maskSensitive(def.input, input, REDACTED);
   // The one place a row-level rule gets its row. Once per invocation, never per row:
   // that asymmetry is what lets the predicate stay synchronous, so a live query can
   // re-evaluate the same policy per subscriber without a query per change event. An
@@ -276,39 +318,73 @@ async function perform(
   // because a rule that reads `row` has to decide what `null` means.
   // The SAME `input` object reaches `def.row` here and `def.handle` below, by reference:
   // `transition()` keys what its rule read on it (`transition-observe.ts`, #702).
-  const row = def.row === undefined ? null : ((await def.row({ input, ctx })) ?? null);
-  guardAction(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
+  const judgeRow = async (): Promise<void> => {
+    // `row` and `handle` are the two places `errors:` judges a throw (`declared-errors.ts`).
+    const load = def.row;
+    const row =
+      load === undefined
+        ? null
+        : ((await judgedHandler(def, name, () => load.call(def, { input, ctx }))) ?? null);
+    guardAction(def.policy, { actor: actorOf(ctx), input, row, ctx, action: name }, surface);
+  };
+  // A finished record is this key's outcome, and the key is this actor's (`idempotency-key.ts`).
+  // The row it decided about may be the row it deleted: a rule asked again judges `null`, and a
+  // committed write answers its own retry with a refusal. So the loader and the rule wait, and
+  // `withIdempotency` answers: the replay, or the conflict for another payload. Who is asking was
+  // already decided, per call, by `guardActionBeforeInput` above: a revoked `can()` is refused
+  // here too. In flight or absent, nothing has been decided yet, so the rule decides.
+  const answered = def.row !== undefined && peeked !== undefined && peeked.status !== 'in-flight';
+  if (!answered) await judgeRow();
 
   // 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
   // the one that covers this invocation, and a second here would only re-time its tail.
+  let started = false;
   const run = async (): Promise<unknown> => {
-    const produced = await Promise.resolve(def.handle({ input, ctx }));
+    started = true;
+    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() }));
     return validateOutput(def.output, produced, name);
   };
+  // The meter is drawn LAST before the handler, on every surface `surface: 'server'` included: a
+  // call refused by the policy, the parse or the rate limit used none of the allowance. Under a key
+  // it is drawn only for a reservation this call CREATED (`beforeRun`), so a replay — of a success
+  // or of a settled failure — draws nothing, and a refusal releases the key for a retry next period.
+  const metered = (): Promise<void> =>
+    def.meter === undefined ? Promise.resolve() : drawMeter(name, def.meter, ctx);
+  // The peek can be stale: a record that lapsed after it leaves this call a FRESH reservation, and
+  // the handler must not run on a rule it skipped. `beforeRun` runs only for a created reservation,
+  // and a refusal there releases it. Spend first, in the order a first call takes them.
+  const beforeRun = async (): Promise<void> => {
+    if (!spentEarly) await spend();
+    if (answered) await judgeRow();
+    await metered();
+  };
 
-  let value: unknown;
-  let wrote = true;
-  if (store === undefined || trace.idempotencyKey === null) {
-    value = await run();
-  } else {
+  try {
+    if (store === undefined || trace.idempotencyKey === null) {
+      await metered();
+      return await run();
+    }
     const outcome = await withIdempotency(store, trace.idempotencyKey, input, run, {
-      ...(spentEarly ? {} : { beforeRun: spend }),
+      ...(spentEarly && !answered && def.meter === undefined ? {} : { beforeRun }),
     });
     if (outcome.replayed) options.onReplay?.();
     trace.replayed = outcome.replayed;
-    wrote = !outcome.replayed;
     // A replay is parsed like a first call. The memory store hands back the live value and the
     // postgres store `JSON.parse(JSON.stringify(v))` — a `Date` on the first call and a `string`
     // on every retry served from Postgres — so the output schema is the one answer to its shape.
-    value = outcome.replayed ? validateOutput(def.output, outcome.value, name) : outcome.value;
+    return outcome.replayed ? validateOutput(def.output, outcome.value, name) : outcome.value;
+  } finally {
+    // Only for a handler that actually started, and only through the gate. A replay ran no handler
+    // and changed nothing the first call had not already busted — re-busting per retry re-purges
+    // the CDN and re-queues ISR for a write nobody made. A handler that THREW is busted too: it may
+    // have committed (`withIdempotency` records the same throw for that reason), and skipping the
+    // bust hid that write behind a stale cache for the TTL. The bust is post-COMMIT either way —
+    // invoked inside a transaction, it waits for the root commit and is dropped by a rollback — and
+    // `bustAfterCommit` never throws, so it cannot replace this call's answer or its failure.
+    if (started && def.cache !== undefined) await bustAfterCommit(name, def.cache.invalidates);
   }
-  // Only for a run that actually happened, and only through the gate. A replay ran no handler
-  // and changed nothing the first call had not already busted — re-busting per retry re-purges
-  // the CDN and re-queues ISR for a write nobody made. And the bust is post-COMMIT either way —
-  // invoked inside a transaction, it waits for the root commit and is dropped by a rollback — so
-  // `bustAfterCommit` swallowing its own failure is what keeps a dead cache from turning a
-  // durable write into a failed action.
-  if (wrote && def.cache !== undefined) await bustAfterCommit(name, def.cache.invalidates);
-  return value;
 }

package/src/json-schema.ts

@@ -15,7 +15,7 @@ export type JsonSchemaObject = Record<string, unknown>;
  * `{ type: 'object', additionalProperties: true }` so that "a missing OpenAPI detail must not
  * break a deploy" — which inverts axiom 3: the deploy succeeded and every caller was lied to.
  * `toJsonSchema` throws exactly when the spec must not claim anything, and the same schema
- * still fails `validateInput` on every payload, so the OpenAPI component and the MCP
+ * still fails `parseActionInput` on every payload, so the OpenAPI component and the MCP
  * `inputSchema` were advertising "any object accepted" for an endpoint that accepts none.
  * `registerAction` calls this at boot (`assertProjectable`), so a registered action can never
  * reach a projection that throws.

package/src/meter-gate.ts

@@ -0,0 +1,103 @@
+/**
+ * Where a declared `meter:` is drawn: once per call, inside `invoke`, on EVERY surface — HTTP, MCP,
+ * a job, an in-process call — after the policy admitted it and before the handler starts. A
+ * refusal is `X_METER_EXCEEDED`; a crossed `warnAt` enqueues the app's `onWarn` once per period.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { isAnonymous, logger } from '@ultimat3/core';
+import { MeterExceededError, MeterInvalidError } from './errors-meter';
+import type { ActionMeter, MeterWarning, ResolvedLimit } from './meter';
+import { isMeterLimit } from './meter';
+import { meterPeriodKey, meterWindow } from './meter-period';
+import type { MeterKey, MeterStore } from './meter-store';
+import { getMeterStore } from './meter-store';
+import { inJobFrame, UNATTRIBUTED_JOB } from './rate-limit-gate';
+
+/**
+ * Whose counter: the tenant, else the signed-in actor, else ONE shared counter per population —
+ * refused together rather than unlimited, the rate limiter's rule for a caller with nothing to key
+ * on. A job run carries its org on the worker's anonymous actor (`jobRunActor`), so it counts
+ * there; a tenantless one counts as `job:unattributed`, never on the anonymous visitors' counter.
+ */
+export function meterSubject(ctx: Ctx): string {
+  const orgId = ctx.actor.orgId;
+  if (typeof orgId === 'string' && orgId !== '') return `org:${orgId}`;
+  if (!isAnonymous(ctx.actor)) return `actor:${ctx.actor.id}`;
+  return inJobFrame() ? UNATTRIBUTED_JOB : 'anonymous';
+}
+
+/** A call-time limit, checked: `NaN`, a fraction or a negative is the app's bug, never allow-all. */
+export async function resolveMeterLimit(
+  meter: string,
+  limit: ResolvedLimit,
+  ctx: Ctx,
+): Promise<number> {
+  const resolved: unknown = typeof limit === 'function' ? await limit({ ctx }) : limit;
+  if (!isMeterLimit(resolved)) {
+    throw new MeterInvalidError(meter, 'limit', 'a whole number of calls, 0 or more', resolved);
+  }
+  return resolved;
+}
+
+/** Draw one call from `meter` for this caller, or throw `X_METER_EXCEEDED`. */
+export async function drawMeter(
+  action: string,
+  meter: ActionMeter,
+  ctx: Ctx,
+  store: MeterStore = getMeterStore(),
+): Promise<void> {
+  const limit = await resolveMeterLimit(meter.name, meter.limit, ctx);
+  const nowMs = ctx.now().getTime();
+  const window = meterWindow(meter.period, nowMs);
+  const key: MeterKey = {
+    subject: meterSubject(ctx),
+    meter: meter.name,
+    period: meterPeriodKey(meter.period),
+  };
+  const drawn = await store.draw({ ...key, periodStartMs: window.startMs, limit });
+  if (!drawn.allowed) {
+    throw new MeterExceededError({
+      action,
+      meter: meter.name,
+      period: meter.period,
+      limit,
+      resetsAtMs: window.endMs,
+      nowMs,
+    });
+  }
+  // After the increment landed, never before: a warning for a draw that was refused is a warning
+  // about usage that never happened.
+  if (meter.warnAt === undefined || meter.onWarn === undefined || drawn.warned) return;
+  if (drawn.used < Math.ceil(meter.warnAt * limit)) return;
+  if (!(await store.claimWarning(key, window.startMs))) return;
+  const warning: MeterWarning = {
+    action,
+    meter: meter.name,
+    orgId: ctx.actor.orgId ?? null,
+    actorId: isAnonymous(ctx.actor) ? null : ctx.actor.id,
+    used: drawn.used,
+    limit,
+    periodStart: new Date(window.startMs).toISOString(),
+    resetsAt: new Date(window.endMs).toISOString(),
+  };
+  try {
+    // Outside the caller's transaction: the claim above is already durable, and a warning staged
+    // in a transaction that rolls back would be a claim nothing ever delivers.
+    await meter.onWarn.enqueue(warning, {
+      outbox: false,
+      ...(warning.orgId === null ? {} : { tenantId: warning.orgId }),
+    });
+  } catch (error) {
+    // The call is owed its answer: its draw counted and the handler is about to run, so a warning
+    // that could not be queued never fails it. The claim goes back, so the next draw retries.
+    logger.error('action.meter.warn-failed', { action, meter: meter.name, error });
+    await store.releaseWarning(key, window.startMs).catch((releaseError: unknown) => {
+      logger.error('action.meter.warn-release-failed', {
+        action,
+        meter: meter.name,
+        error: releaseError,
+      });
+    });
+  }
+}