@cplieger/actions 3.0.0 → 3.1.0

package/README.md

@@ -49,7 +49,7 @@ await deleteItem.dispatch(itemId);
 
 The framework provides three adapter injection points:
 
-- **Notifier** (`configure()`): Provides `success(msg)` and `error(msg, retry?)` methods for displaying notifications. Without configuration, notifications are silently dropped.
+- **Notifier** (`configure()`): Provides `success(msg)` and `error(msg, retry?)` methods for displaying notifications. Without configuration, notifications are dropped — and the framework warns once on the first drop, since a forgotten `configure()` call is otherwise invisible. Call `configure({})` to opt into intentional headless silence (tests, non-UI environments); an explicitly configured notifier never warns, even with missing methods.
 
 - **API** (`configureApi()`): Configures the HTTP layer used by all `apiAction` instances — base URL, auth/CSRF headers, credentials mode, or a custom fetch implementation. Without configuration, `apiAction` uses the global `fetch` with relative paths.
 
@@ -93,17 +93,86 @@ const action = apiAction({
 });
 ```
 
+### Response decoding (apiAction `decode` / `decodeError`)
+
+By default `apiAction` treats any 2xx as success and any failure as an
+`ActionError`. Two optional hooks own the interpretation for servers that
+speak nonstandard envelopes:
+
+`decode(data, { status, spec })` runs on every 2xx. Return the action result,
+or **throw** to route the dispatch to the error branch (rollback + error
+notification + registry error status) — the seam for 200-with-error envelopes:
+
+```typescript
+const stage = apiAction<{ repo: string }, { output?: string }>({
+  name: "git.stage",
+  request: (args) => ({ method: "POST", path: "/api/git/stage", body: args }),
+  // The server replies HTTP 200 for both outcomes; a non-empty `error`
+  // field is the failure signal.
+  decode: (data) => {
+    if (hasErrorString(data) && data.error !== "") {
+      throw new ActionError(data.error, { code: "git" });
+    }
+    return data as { output?: string };
+  },
+});
+```
+
+`decodeError(info, { spec })` runs on every failure that produced a real HTTP
+response. `info` carries `status`, `message`, `code?`, the parsed JSON
+`body?`, and `headers?`. Return `{ kind: "success", value }` to resolve the
+dispatch as success (a 409 whose body is a meaningful payload), `{ kind:
+"error", error }` to replace the default error, or `undefined` to keep the
+default mapping:
+
+```typescript
+const deleteTool = apiAction<{ name: string }, DeleteToolResult>({
+  name: "tools.delete",
+  request: ({ name }) => ({ method: "DELETE", path: `/api/tools/${name}` }),
+  error: false, // 409 cascade is a normal flow, handled by the caller
+  decodeError: (info) =>
+    info.status === 409
+      ? { kind: "success", value: (info.body ?? {}) as DeleteToolResult }
+      : undefined,
+});
+```
+
+Transport-level failures (network / timeout / cancellation — `status` 0)
+never reach `decodeError`, so `retryNetwork` classification and cancellation
+semantics can't be accidentally rewritten. `info.body` is server-controlled
+input: validate its shape before reading fields.
+
+For nonstandard **request** bodies, `RequestSpec.rawBody` is the encoder
+seam: a pre-encoded `BodyInit` sent as-is (no JSON encoding, no automatic
+Content-Type — set the type via `headers`), computed per dispatch by the
+`request()` function:
+
+```typescript
+const saveConfig = apiAction<string, unknown>({
+  name: "config.save",
+  request: (yaml) => ({
+    method: "PUT",
+    path: "/api/config",
+    rawBody: yaml,
+    headers: { "Content-Type": "text/yaml" },
+  }),
+});
+```
+
+`run()` on a plain `defineAction` remains the universal escape hatch for wire
+contracts beyond these seams.
+
 ## API
 
 - `configure(notifier)` — inject the notification adapter
 - `configureApi(opts)` — configure the HTTP layer (baseUrl, headers, credentials, fetchFn)
 - `configureTransport(fn)` — inject the streaming transport adapter
-- `defineAction(def)` — create an action from a declarative definition
-- `apiAction(def)` — create an HTTP-backed action (uses `fetch`)
+- `defineAction(def)` — create an action from a declarative definition. Action names should be unique: a duplicate name gets a one-time console warning, since the registry log and the name-keyed helpers (`isPending`, `subscribeByName`, `bindLoadingState`) conflate same-named definitions
+- `apiAction(def)` — create an HTTP-backed action (uses `fetch`); optional `decode` / `decodeError` hooks own nonstandard-envelope interpretation (see above)
 - `transportAction(def)` — create a transport/SSE-backed action
 - `debouncedDispatch(action, opts)` — debounce wrapper
 - `pollAction(action, args, opts)` — interval polling with pause/backoff
-- `bindLoadingState(name, el, opts?)` — bind an element's disabled/aria-busy state to action pending; a reactive effect over the pending signals
+- `bindLoadingState(name, el, opts?)` — bind an element's disabled/aria-busy state to action pending; a reactive effect over the pending signals. The binding auto-disposes when the element leaves the DOM — an element re-attached later (e.g. a list re-render reusing nodes) is no longer bound and needs a fresh `bindLoadingState` call
 - `pollUntil(step, opts)` — poll until a terminal condition (wait-then-poll, `until` predicate, `maxAttempts`/`timeoutMs` budgets, backoff-on-transient); returns `{status:'done'|'timeout'|'aborted'}`. A standalone sibling to `pollAction` for one-shot terminal-state waits.
 - `withAsyncFeedback(btn, fn, opts?)` — per-button async feedback (spinner → ✓/✗ → restore) with a re-entry guard + sr-only announce + injectable glyphs. `target?: HTMLElement` runs the cycle on a child slot via in-place element replacement (siblings/label untouched); `resetMs: 0` persists the outcome glyph (no auto-revert).
 - `subscribeToActions(fn)` — subscribe to all lifecycle events (discrete event stream)
@@ -117,6 +186,8 @@ const action = apiAction({
 - `classifyFetchError(err)` — classify fetch errors (network vs timeout vs HTTP)
 - `hasErrorString(err)` — type guard for objects with a `.message` string
 - `RETRY_STANDARD` — standard retry config (2 retries, 300ms)
+- `IDEMPOTENCY_HEADER` — the `Idempotency-Key` HTTP header name `apiAction` sets from `ctx.idempotencyKey`; import it in custom `run()` implementations instead of hand-copying the literal
+- `IDEMPOTENCY_COMMAND_FIELD` — the `idempotency_key` command field `transportAction` injects; same sharing purpose for custom transport runners
 
 > `withTimeout(signal, ms)` and `API_TIMEOUT_MS` moved to [`@cplieger/fetch`](https://github.com/cplieger/fetch) (the layer that owns timeout composition); import them from there.
 
@@ -167,6 +238,35 @@ handle.abort();
 const result = await handle;
 ```
 
+### Typed outcome accessor (`handle.outcome`)
+
+The handle's own resolution is deliberately never-rejecting `TResult | null`,
+which collapses three terminal states — and makes a legitimately-`null`
+result indistinguishable from failure. `handle.outcome` is the opt-in typed
+accessor for callers that need the distinction:
+
+```typescript
+const handle = action.dispatch(args);
+const outcome = await handle.outcome; // never rejects
+switch (outcome.status) {
+  case "success":
+    use(outcome.value); // TResult — including a legitimate null
+    break;
+  case "error":
+    show(outcome.error.message); // the normalized ActionErrorLike
+    break;
+  case "cancelled":
+    break; // abort() / action.cancel() / timeout-as-abort
+}
+```
+
+`outcome.attempts` carries the run count when the dispatch actually ran
+(retries increment it); a dedupe-joined dispatch resolves with the shared
+result but no attempts. The never-rejecting promise and the callback tiers
+(`onSuccess`/`onError`/`onSettled`) remain the canonical surface — reach for
+`.outcome` when a call site consumes the terminal state inline instead of
+wiring callbacks.
+
 ### Timeout option
 
 `ActionDefinition` accepts a `timeout` (ms) that aborts `run()` via `AbortSignal.timeout()`:
@@ -193,7 +293,6 @@ The following features are intentionally not implemented:
 | Debounce `maxWait`                     | Deliberate simplification. Use `flush()` for guaranteed-fire semantics.                           |
 | Throttle helper                        | Not action-specific. Consumers can throttle before calling `dispatch()`.                          |
 | `condition` / pre-execution guard      | Trivially implemented by callers with `if`. `dedupe` covers the primary use case.                 |
-| Typed discriminated-union result       | The callback model (onSuccess/onError/onSettled) is the chosen API shape.                         |
 | `onProgress` callback                  | Transport-specific. Consumers wire progress in their `run()` implementation.                      |
 | Batch dispatch                         | Store-level concern. This library doesn't own a store.                                            |
 | `dispose()` / action deregistration    | Actions are lightweight when idle. Not a leak concern for realistic app sizes.                    |

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/actions",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "exports": {
     ".": "./src/index.ts",
     "./testing": "./src/testing.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/actions",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -13,8 +13,13 @@
     "test": "vitest --run"
   },
   "dependencies": {
-    "@cplieger/fetch": "2.0.0",
-    "@cplieger/reactive": "1.2.4"
+    "@cplieger/fetch": "2.1.0",
+    "@cplieger/reactive": "1.2.5"
+  },
+  "overrides": {
+    "typed-rest-client": {
+      "qs": "6.15.3"
+    }
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -29,7 +34,7 @@
     "happy-dom": "20.10.6",
     "prettier": "3.9.5",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.63.0",
+    "typescript-eslint": "8.64.0",
     "vitest": "4.1.10"
   },
   "description": "Declarative async UI-action framework for TypeScript",

package/src/api.ts

@@ -11,7 +11,13 @@ import type { ApiErr, FetchConfig, FetchInstance, RequestOptions } from "@cplieg
 
 import { defineAction, IDEMPOTENCY_HEADER } from "./define.js";
 import { ActionError } from "./error.js";
-import type { Action, ActionContext, ActionDefinition, RequestSpec } from "./types.js";
+import type {
+  Action,
+  ActionContext,
+  ActionDefinition,
+  ActionErrorLike,
+  RequestSpec,
+} from "./types.js";
 
 const JSON_CT = "application/json";
 
@@ -91,6 +97,35 @@ export function _resetApiConfigForTest(): void {
 
 // ---------------------------------------------------------------------------
 
+/** Context passed to the {@link ApiActionDefinition.decode} hook. */
+export interface ApiDecodeContext {
+  /** HTTP status of the 2xx response being decoded. */
+  readonly status: number;
+  /** The request descriptor this response answers. */
+  readonly spec: RequestSpec;
+}
+
+/** A failed request as seen by {@link ApiActionDefinition.decodeError}: the
+ *  real HTTP response's status, the message the fetch layer lifted, the
+ *  server-supplied code (when present), the parsed JSON body (when one
+ *  parsed), and the response headers. Transport-level failures (network /
+ *  timeout / cancellation / invalid — status 0) never reach the hook. */
+export interface ApiErrorInfo {
+  readonly status: number;
+  readonly message: string;
+  readonly code?: string;
+  /** Parsed JSON body of the failed response. Server-controlled input —
+   *  validate the shape before reading fields. */
+  readonly body?: unknown;
+  readonly headers?: Headers;
+}
+
+/** Return shape of {@link ApiActionDefinition.decodeError}: resolve the
+ *  dispatch as a success carrying `value`, or replace the default error. */
+export type ApiErrorDecision<TResult> =
+  | { readonly kind: "success"; readonly value: TResult }
+  | { readonly kind: "error"; readonly error: ActionErrorLike };
+
 /** Caller-facing shape of an apiAction definition. Replaces `run` with
  *  a `request` function that returns an HTTP {@link RequestSpec}. */
 export interface ApiActionDefinition<TArgs, TResult, TOp = unknown> extends Omit<
@@ -98,6 +133,26 @@ export interface ApiActionDefinition<TArgs, TResult, TOp = unknown> extends Omit
   "run"
 > {
   request: (args: TArgs) => RequestSpec;
+
+  /** Decode / validate a 2xx response body. Receives the raw decoded body
+   *  (`undefined` for a 204 / empty-body response) and returns the action
+   *  result; throw (an {@link ActionError}) to route the dispatch to the
+   *  error branch instead (rollback + error notification + registry error) —
+   *  the seam for 200-with-error envelopes. Absent: the body is returned as
+   *  `TResult` unchanged. */
+  decode?: (data: unknown, ctx: ApiDecodeContext) => TResult;
+
+  /** Reinterpret a failed request that produced a real HTTP response. Return
+   *  `{ kind: "success", value }` to resolve the dispatch as success (e.g. a
+   *  409 whose body is a meaningful payload), `{ kind: "error", error }` to
+   *  replace the default error, or `undefined` to keep the default
+   *  {@link ActionError} mapping. Transport failures (status 0: network /
+   *  timeout / cancelled / invalid) never reach this hook, so retry
+   *  classification and cancellation semantics are preserved. */
+  decodeError?: (
+    info: ApiErrorInfo,
+    ctx: { readonly spec: RequestSpec },
+  ) => ApiErrorDecision<TResult> | undefined;
 }
 
 /**
@@ -109,12 +164,12 @@ export interface ApiActionDefinition<TArgs, TResult, TOp = unknown> extends Omit
 export function apiAction<TArgs, TResult = unknown, TOp = unknown>(
   def: ApiActionDefinition<TArgs, TResult, TOp>,
 ): Action<TArgs, TResult> {
-  const { request, ...rest } = def;
+  const { request, decode, decodeError, ...rest } = def;
   return defineAction<TArgs, TResult, TOp>({
     ...rest,
     run: async (args, signal, ctx) => {
       const spec = request(args);
-      return executeRequest<TResult>(spec, signal, ctx);
+      return executeRequest<TResult>(spec, signal, ctx, decode, decodeError);
     },
   });
 }
@@ -123,6 +178,11 @@ async function executeRequest<T>(
   spec: RequestSpec,
   signal: AbortSignal,
   ctx?: ActionContext,
+  decode?: (data: unknown, dctx: ApiDecodeContext) => T,
+  decodeError?: (
+    info: ApiErrorInfo,
+    dctx: { readonly spec: RequestSpec },
+  ) => ApiErrorDecision<T> | undefined,
 ): Promise<T> {
   // Build the request headers here (not via fetch's prepareHeaders seam):
   // actions' hook is spec-aware and receives { spec }, which fetch's plain
@@ -163,12 +223,24 @@ async function executeRequest<T>(
     timeoutMs: API_TIMEOUT_MS,
     headers: effectiveHeaders,
   };
-  if (spec.method !== "GET" && spec.body !== undefined) {
-    opts.body = spec.body;
+  if (spec.method !== "GET") {
+    if (spec.rawBody !== undefined) {
+      // Pre-encoded body: fetch sends it as-is (no JSON encoding, no
+      // automatic Content-Type — spec.headers carries the type).
+      opts.rawBody = spec.rawBody;
+    } else if (spec.body !== undefined) {
+      opts.body = spec.body;
+    }
   }
 
   const result = await apiFetch.requestRaw<T>(spec.method, spec.path, opts);
   if (result.ok) {
+    if (decode !== undefined) {
+      // The decoder owns 2xx interpretation: its return is the action result,
+      // its throw routes the dispatch to the error branch (the seam for
+      // 200-with-error envelopes).
+      return decode(result.data, { status: result.status, spec });
+    }
     // fetch collapses a 204 and an empty-body 2xx to data === undefined. Warn
     // on an unexpected empty body (a non-204, non-DELETE response), as before.
     if (result.data === undefined && result.status !== 204 && spec.method !== "DELETE") {
@@ -178,6 +250,34 @@ async function executeRequest<T>(
     }
     return result.data;
   }
+  // decodeError sees only real HTTP responses (status > 0): transport-level
+  // failures keep the default mapping so retryNetwork classification and
+  // cancellation semantics cannot be accidentally rewritten by the hook.
+  if (decodeError !== undefined && result.status > 0) {
+    const decision = decodeError(
+      {
+        status: result.status,
+        message: result.error,
+        ...(result.code !== undefined && { code: result.code }),
+        ...(result.body !== undefined && { body: result.body }),
+        ...(result.headers !== undefined && { headers: result.headers }),
+      },
+      { spec },
+    );
+    if (decision !== undefined) {
+      if (decision.kind === "success") {
+        return decision.value;
+      }
+      const e = decision.error;
+      throw e instanceof ActionError
+        ? e
+        : new ActionError(e.message, {
+            ...(e.status !== undefined && { status: e.status }),
+            ...(e.code !== undefined && { code: e.code }),
+            ...(e.cause !== undefined && { cause: e.cause }),
+          });
+    }
+  }
   throw actionErrorFromApiErr(result);
 }
 

package/src/debounce.ts

@@ -59,7 +59,10 @@ export function debouncedDispatch<TArgs, TResult>(
       void action.dispatch(args);
       lastFiredAt = now;
       lastArgs = undefined;
-      pending = true;
+      // Nothing is scheduled after a leading-edge fire — the timer below is a
+      // cooldown re-arm, not a pending dispatch — so isPending() reads false
+      // until a call lands inside the quiet window (doc contract above).
+      pending = false;
       if (timer !== undefined) {
         clearTimeout(timer);
       }
@@ -88,7 +91,9 @@ export function debouncedDispatch<TArgs, TResult>(
     lastArgs = undefined;
     if (a !== undefined) {
       lastFiredAt = Date.now();
-      pending = true;
+      // The coalesced args fire now; the re-armed timer is a cooldown window
+      // with nothing scheduled in it yet, so isPending() reads false.
+      pending = false;
       timer = setTimeout(fireTrailing, opts.wait);
       void action.dispatch(a);
     } else {

package/src/define.ts

@@ -19,12 +19,21 @@ import type {
   ActionContext,
   ActionDefinition,
   ActionErrorLike,
+  ActionOutcome,
   DispatchHandle,
   DispatchOptions,
 } from "./types.js";
 
 let instanceCounter = 0;
 
+/** Monotonic per-definition id, prefixed onto dedupe keys so two definitions
+ *  that happen to share a name can never join each other's in-flight promise
+ *  (the cross-definition `as TResult` type-confusion hazard). */
+let defCounter = 0;
+
+/** Names seen by defineAction, for the duplicate-name diagnostic. */
+const registeredNames = new Set<string>();
+
 const NO_OPTS = Object.freeze({}) as DispatchOptions;
 const NOOP = (): void => {
   /* noop */
@@ -60,10 +69,15 @@ function generateIdempotencyKey(): string {
 
 const scopeChains = new Map<string, Promise<unknown>>();
 
-/** Create a DispatchHandle: a Promise augmented with abort(). */
-function makeHandle<T>(promise: Promise<T | null>, abortFn: () => void): DispatchHandle<T> {
-  const handle = promise as DispatchHandle<T>;
+/** Create a DispatchHandle: a Promise augmented with abort() + outcome. */
+function makeHandle<T>(
+  promise: Promise<T | null>,
+  abortFn: () => void,
+  outcome: Promise<ActionOutcome<T>>,
+): DispatchHandle<T> {
+  const handle = promise as DispatchHandle<T> & { outcome: Promise<ActionOutcome<T>> };
   handle.abort = abortFn;
+  handle.outcome = outcome;
   return handle;
 }
 
@@ -81,6 +95,15 @@ const activeDedupes = new Map<string, DedupeSlot>();
 export function defineAction<TArgs, TResult, TOp = unknown>(
   def: ActionDefinition<TArgs, TResult, TOp>,
 ): Action<TArgs, TResult> {
+  defCounter += 1;
+  const defId = defCounter;
+  if (registeredNames.has(def.name)) {
+    console.warn(
+      `[actions] duplicate action name "${def.name}" — the registry log and name-keyed helpers (isPending, subscribeByName, bindLoadingState) will conflate the two definitions`,
+    );
+  } else {
+    registeredNames.add(def.name);
+  }
   const inFlight = new Map<string, AbortController>();
   const started = new Set<string>();
   const scopeSkipResolvers = new Map<string, () => void>();
@@ -112,11 +135,48 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
       });
     }
   }
+  /** Fire the definition-level then per-dispatch success callbacks — the one
+   *  block shared by the executing path and the dedupe-join path. */
+  function fireSuccessCallbacks(
+    result: TResult,
+    args: TArgs,
+    opts: DispatchOptions<TArgs, TResult>,
+  ): void {
+    fireDefSuccess(result, args);
+    const onSuccessCb = opts.onSuccess;
+    if (onSuccessCb) {
+      safeInvoke(def.name, "onSuccess", () => {
+        onSuccessCb(result, args);
+      });
+    }
+  }
+  /** Fire the definition-level then per-dispatch error callbacks — the one
+   *  block shared by the executing path and the dedupe-join path. */
+  function fireErrorCallbacks(
+    err: ActionErrorLike,
+    args: TArgs,
+    opts: DispatchOptions<TArgs, TResult>,
+  ): void {
+    fireDefError(err, args);
+    const onErrorCb = opts.onError;
+    if (onErrorCb) {
+      safeInvoke(def.name, "onError", () => {
+        onErrorCb(err, args);
+      });
+    }
+  }
 
   function dispatch(
     args: TArgs,
     opts: DispatchOptions<TArgs, TResult> = NO_OPTS,
   ): DispatchHandle<TResult> {
+    // Typed terminal outcome, resolved exactly once at whichever terminal
+    // point this dispatch reaches. Kept OUT of the legacy promise chain so
+    // existing resolution timing is untouched.
+    let resolveOutcome!: (o: ActionOutcome<TResult>) => void;
+    const outcomePromise = new Promise<ActionOutcome<TResult>>((r) => {
+      resolveOutcome = r;
+    });
     const fireSettledHooks = (): void => {
       fireDefSettled(args);
       const onSettledCb = opts.onSettled;
@@ -133,49 +193,40 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
         const shared = entry.promise;
         if (shared === undefined) {
           fireSettledHooks();
-          return makeHandle(Promise.resolve(null) as Promise<TResult | null>, NOOP);
+          resolveOutcome({ status: "cancelled" });
+          return makeHandle(Promise.resolve(null) as Promise<TResult | null>, NOOP, outcomePromise);
         }
         const joined = (shared as Promise<TResult | null>).then(
           (v) => {
             if (v !== null || entry.succeeded === true) {
-              fireDefSuccess(v as TResult, args);
-              const onSuccessCb = opts.onSuccess;
-              if (onSuccessCb) {
-                safeInvoke(def.name, "onSuccess", () => {
-                  onSuccessCb(v as TResult, args);
-                });
-              }
+              fireSuccessCallbacks(v as TResult, args, opts);
+              resolveOutcome({ status: "success", value: v as TResult });
             } else if (entry.error !== undefined) {
               const capturedErr = entry.error;
-              fireDefError(capturedErr, args);
-              const onErrorCb = opts.onError;
-              if (onErrorCb) {
-                safeInvoke(def.name, "onError", () => {
-                  onErrorCb(capturedErr, args);
-                });
-              }
+              fireErrorCallbacks(capturedErr, args, opts);
+              resolveOutcome({ status: "error", error: capturedErr });
             } else if (entry.cancelled !== true) {
               const dedupeErr: ActionErrorLike = {
                 message: "deduped dispatch did not succeed",
                 code: "dedupe",
               };
-              fireDefError(dedupeErr, args);
-              const onErrorCb = opts.onError;
-              if (onErrorCb) {
-                safeInvoke(def.name, "onError", () => {
-                  onErrorCb(dedupeErr, args);
-                });
-              }
+              fireErrorCallbacks(dedupeErr, args, opts);
+              resolveOutcome({ status: "error", error: dedupeErr });
+            } else {
+              resolveOutcome({ status: "cancelled" });
             }
             fireSettledHooks();
             return v;
           },
-          () => {
+          (reason: unknown) => {
+            // Defensive: runOnce never rejects; a rejection here means the
+            // shared promise itself failed. Surface it as an error outcome.
+            resolveOutcome({ status: "error", error: toActionError(reason) });
             fireSettledHooks();
             return null;
           },
         );
-        return makeHandle(joined, NOOP);
+        return makeHandle(joined, NOOP, outcomePromise);
       }
     }
 
@@ -195,11 +246,11 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
 
     let result: Promise<TResult | null>;
     if (scopeKey === null) {
-      result = runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt);
+      result = runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt, resolveOutcome);
     } else {
       const prev = scopeChains.get(scopeKey) ?? Promise.resolve();
       const next = prev.then(() =>
-        runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt),
+        runOnce(args, opts, ac, id, dedupeEntry, dedupeKey, dispatchedAt, resolveOutcome),
       );
       let tailResolve!: () => void;
       const tail = new Promise<void>((r) => {
@@ -241,6 +292,7 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
           });
         } finally {
           fireSettledHooks();
+          resolveOutcome({ status: "cancelled" });
           earlyCancelResolve(null);
         }
       });
@@ -259,9 +311,13 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
       });
     }
 
-    return makeHandle(result, () => {
-      ac.abort();
-    });
+    return makeHandle(
+      result,
+      () => {
+        ac.abort();
+      },
+      outcomePromise,
+    );
   }
 
   function dedupeKeyFor(args: TArgs): string | null {
@@ -270,7 +326,10 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
       return null;
     }
     const argKey = typeof cfg === "function" ? cfg(args) : safeStringify(args);
-    return `${def.name}::${argKey}`;
+    // defId prefix: dedupe joins are per-definition by contract. Without it,
+    // two definitions sharing a name would join each other's in-flight
+    // promise and coerce a foreign result via `as TResult`.
+    return `${String(defId)}::${def.name}::${argKey}`;
   }
 
   function evictDedupeSlot(dk: string | null, entry: DedupeSlot | null): void {
@@ -288,10 +347,12 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
     dedupeEntry: DedupeSlot | null,
     dedupeKey: string | null,
     dispatchedAt: number,
+    resolveOutcome: (o: ActionOutcome<TResult>) => void,
   ): Promise<TResult | null> {
     started.add(id);
     if (!inFlight.has(id) && ac.signal.aborted) {
       started.delete(id);
+      resolveOutcome({ status: "cancelled" });
       return null;
     }
     const settle = (): void => {
@@ -321,6 +382,7 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
         completedAt: now,
       });
       fireDefSettled(args);
+      resolveOutcome({ status: "cancelled" });
       settle();
       return null;
     }
@@ -365,14 +427,9 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
           error: err,
         });
         emitErrorToast(args, err);
-        fireDefError(err, args);
-        const onErrorCb = opts.onError;
-        if (onErrorCb) {
-          safeInvoke(def.name, "onError", () => {
-            onErrorCb(err, args);
-          });
-        }
+        fireErrorCallbacks(err, args, opts);
         fireDefSettled(args);
+        resolveOutcome({ status: "error", error: err });
         settle();
         return null;
       }
@@ -413,6 +470,7 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
           }
         }
         fireDefSettled(args);
+        resolveOutcome({ status: "cancelled" });
         return null;
       }
       record({
@@ -431,14 +489,9 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
       }
       evictDedupeSlot(dedupeKey, dedupeEntry);
       emitSuccessToast(args, result, opts);
-      fireDefSuccess(result, args);
-      const onSuccessCb = opts.onSuccess;
-      if (onSuccessCb) {
-        safeInvoke(def.name, "onSuccess", () => {
-          onSuccessCb(result, args);
-        });
-      }
+      fireSuccessCallbacks(result, args, opts);
       fireDefSettled(args);
+      resolveOutcome({ status: "success", value: result, attempts });
       return result;
     } catch (e: unknown) {
       const err = toActionError(e);
@@ -474,15 +527,18 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
       }
       if (!cancelled) {
         emitErrorToast(args, err);
-        fireDefError(err, args);
-        const onErrorCb = opts.onError;
-        if (onErrorCb) {
-          safeInvoke(def.name, "onError", () => {
-            onErrorCb(err, args);
-          });
-        }
+        fireErrorCallbacks(err, args, opts);
       }
       fireDefSettled(args);
+      if (cancelled) {
+        resolveOutcome({ status: "cancelled" });
+      } else {
+        resolveOutcome({
+          status: "error",
+          error: err,
+          ...(attempts !== undefined && { attempts }),
+        });
+      }
       return null;
     } finally {
       settle();
@@ -688,9 +744,12 @@ export function defineAction<TArgs, TResult, TOp = unknown>(
   return action;
 }
 
-/** Test-only: reset the instance counter + scope chains + dedupe map. */
+/** Test-only: reset the instance/definition counters + name registry +
+ *  scope chains + dedupe map. */
 export function _resetForTest(): void {
   instanceCounter = 0;
+  defCounter = 0;
+  registeredNames.clear();
   _resetSymbols();
   scopeChains.clear();
   activeDedupes.clear();

package/src/index.ts

@@ -6,13 +6,19 @@ export { configure } from "./notifier.js";
 export type { Notifier, NotifierRetry } from "./notifier.js";
 
 // Transport injection
-export { configureTransport, transportAction } from "./transport.js";
+export { configureTransport, transportAction, IDEMPOTENCY_COMMAND_FIELD } from "./transport.js";
 export type { TransportSendResult, TransportCommand, TransportSendFn } from "./transport.js";
 
 // Action factories
-export { defineAction } from "./define.js";
+export { defineAction, IDEMPOTENCY_HEADER } from "./define.js";
 export { apiAction, configureApi } from "./api.js";
-export type { ApiConfig, ApiActionDefinition } from "./api.js";
+export type {
+  ApiConfig,
+  ApiActionDefinition,
+  ApiDecodeContext,
+  ApiErrorInfo,
+  ApiErrorDecision,
+} from "./api.js";
 
 // Error class + utilities
 export { ActionError, hasErrorString, classifyFetchError, retryNetwork } from "./error.js";
@@ -56,6 +62,7 @@ export type {
   ActionErrorLike,
   ActionInstance,
   ActionLifecycleStatus,
+  ActionOutcome,
   DispatchHandle,
   DispatchOptions,
   NotificationSpec,

package/src/notifier.ts

@@ -25,23 +25,52 @@ export interface Notifier {
 }
 
 let _notifier: Notifier = {};
+let _configured = false;
+let _warnedUnconfigured = false;
 
-/** Configure the global notifier adapter. Call once at app boot. */
+/** Configure the global notifier adapter. Call once at app boot. Passing an
+ *  empty object (`configure({})`) is the explicit headless opt-in: it keeps
+ *  notifications silently dropped without the unconfigured-drop warning. */
 export function configure(notifier: Notifier): void {
   _notifier = notifier;
+  _configured = true;
+}
+
+/** Warn once, on the first notification dropped because configure() was
+ *  never called — the silent-by-default footgun. An explicit configure()
+ *  (even with missing methods) is a deliberate headless choice and stays
+ *  silent, matching the documented Notifier contract. */
+function warnUnconfiguredDrop(kind: string): void {
+  if (_configured || _warnedUnconfigured) {
+    return;
+  }
+  _warnedUnconfigured = true;
+  console.warn(
+    `[actions] ${kind} notification dropped — configure() was never called. Wire a notifier at boot, or call configure({}) for intentional headless silence. This warning fires once.`,
+  );
 }
 
 /** @internal Emit a success notification. */
 export function notifySuccess(message: string): void {
-  _notifier.success?.(message);
+  if (_notifier.success === undefined) {
+    warnUnconfiguredDrop("success");
+    return;
+  }
+  _notifier.success(message);
 }
 
 /** @internal Emit an error notification. */
 export function notifyError(message: string, retry?: NotifierRetry): void {
-  _notifier.error?.(message, retry);
+  if (_notifier.error === undefined) {
+    warnUnconfiguredDrop("error");
+    return;
+  }
+  _notifier.error(message, retry);
 }
 
 /** @internal Test-only: reset the notifier to the default no-op. */
 export function _resetNotifierForTest(): void {
   _notifier = {};
+  _configured = false;
+  _warnedUnconfigured = false;
 }

package/src/registry.ts

@@ -1,16 +1,46 @@
 // Action registry: in-memory log of all dispatched actions with a
-// subscribe API. Fires per state transition. Bounded to a recent
-// window so memory usage stays flat over a long session.
+// subscribe API. Fires per state transition.
 //
-// Performance: eviction uses a head-pointer + tombstones instead of
-// splice + O(n) index re-computation. record() is O(1) amortized.
+// Shape: two single-purpose structures with disjoint lifetimes, so the
+// pending accounting cannot desync from log eviction by construction.
+//
+//   - `inflight` holds the pending dispatches. Entries live exactly as
+//     long as their dispatch is in flight; the table never evicts by
+//     count (only the leak watchdog reclaims past MAX_INFLIGHT), so a
+//     pending entry can never be displaced by log churn.
+//   - `settled` holds terminal snapshots, latest-per-dispatch-id,
+//     bounded to MAX_LOG_SIZE by evicting the lowest-seq entry
+//     (first-record order — the same victim the old single-array
+//     shape picked).
+//
+// A per-dispatch monotonic `seq`, stamped at first record, orders the
+// recomposed getActionLog() view identically to the old array's
+// insertion order.
+//
+// Transition table for record(instance). The caller contract
+// (define.ts) records one pending then at most one terminal per
+// dispatch id, and an id's `name` never changes across records (ids
+// embed their action name). Every cell is still defined so an
+// out-of-contract input degrades to sane accounting rather than a
+// desync; reentrant records from synchronous signal effects land on
+// coherent state because each transition completes its map moves
+// before publishing signals:
+//
+//   status   | id in inflight       | id in settled          | id unknown
+//   ---------|----------------------|------------------------|--------------------
+//   pending  | overwrite instance   | move back to inflight  | insert (new seq),
+//            | (keep seq)           | (keep seq), re-index   | index, watchdog
+//   terminal | move to settled      | overwrite instance     | insert into settled
+//            | (keep seq), unindex  | (keep seq + position)  | (new seq), evict
 //
 // Pending state (isPending / pendingCount) is mirrored into reactive signals,
 // so it can be read inside an effect — bindLoadingState is a plain effect over
-// these, not a bespoke subscription. The pendingByName Set stays the source of
-// truth for which ids are in flight; the signals expose the derived counts.
-// The lifecycle fan-out below (record → listeners) is a discrete event stream
-// and stays a plain emitter — events are not reactive state.
+// these, not a bespoke subscription. The pendingByName Set index over
+// `inflight` is the per-name source of truth; the signals expose the derived
+// counts, and the total is `inflight.size` (membership, not paired
+// arithmetic — an unpaired decrement is unrepresentable). The lifecycle
+// fan-out below (record → listeners) is a discrete event stream and stays a
+// plain emitter — events are not reactive state.
 // ---------------------------------------------------------------------------
 
 import { signal, batch, SignalMap } from "@cplieger/reactive";
@@ -18,154 +48,186 @@ import { signal, batch, SignalMap } from "@cplieger/reactive";
 import type { ActionInstance, RegistryListener } from "./types.js";
 
 const MAX_LOG_SIZE = 200;
-const MAX_LOG_HARD = MAX_LOG_SIZE * 5;
 
-const log: (ActionInstance | null)[] = [];
-interface LogSlot {
+/** Leak watchdog threshold for the in-flight table. `settled` is bounded by
+ *  construction, so only a dispatch that never settles (a lifecycle bug in
+ *  the defining layer) can grow state — past this many in-flight entries the
+ *  oldest is reclaimed with a console.warn naming it. This bounds the
+ *  in-flight population specifically; the old shape's equivalent tier
+ *  (MAX_LOG_HARD) bounded the combined log. */
+const MAX_INFLIGHT = 1000;
+
+interface LogEntry {
   instance: ActionInstance;
-  index: number;
+  /** Monotonic stamp assigned at the dispatch id's FIRST record; preserved
+   *  across every transition so the recomposed log keeps first-record order. */
+  readonly seq: number;
 }
-const idMap = new Map<string, LogSlot>();
+
+const inflight = new Map<string, LogEntry>();
+const settled = new Map<string, LogEntry>();
+let seqCounter = 0;
+
 const listeners = new Set<RegistryListener>();
 const namedListeners = new Map<string, Set<RegistryListener>>();
 const pendingByName = new Map<string, Set<string>>();
-let _pendingTotal = 0;
-let _liveCount = 0;
-let _head = 0;
-
-// Test-only: when true, a detected _pendingTotal underflow throws instead of
-// the production warn + clamp, so an add/removePending pairing bug surfaces in
-// tests rather than being silently masked. Production default is false.
-// Toggled via _setThrowOnInvariantViolationForTest (same _*ForTest convention
-// as _resetForTest); reset to false by _resetForTest.
-let _throwOnInvariantViolation = false;
 
-// Reactive mirrors of the pending state. pendingByName remains the source of
-// truth; these signals expose the derived counts so isPending/pendingCount can
-// be read reactively (e.g. by bindLoadingState's effect).
+// Reactive mirrors of the pending state. The inflight table + its name index
+// remain the source of truth; these signals expose the derived counts so
+// isPending/pendingCount can be read reactively (e.g. by bindLoadingState's
+// effect).
 const pendingSigs = new SignalMap<number>();
 const pendingTotalSig = signal(0);
 
-function addPending(name: string, id: string): void {
+/** Add `id` to the name index + refresh the signals. Call AFTER the inflight
+ *  mutation so `inflight.size` is current. */
+function indexPending(name: string, id: string): void {
   let s = pendingByName.get(name);
   if (s === undefined) {
     s = new Set();
     pendingByName.set(name, s);
   }
-  if (s.has(id)) {
-    return;
-  }
   s.add(id);
-  _pendingTotal++;
   const size = s.size;
   batch(() => {
     pendingSigs.ensure(name, 0).value = size;
-    pendingTotalSig.value = _pendingTotal;
+    pendingTotalSig.value = inflight.size;
   });
 }
 
-function removePending(name: string, id: string): void {
+/** Remove `id` from the name index + refresh the signals. Call AFTER the
+ *  inflight mutation. No-op when the id was never indexed. */
+function unindexPending(name: string, id: string): void {
   const s = pendingByName.get(name);
   if (!s?.delete(id)) {
     return;
   }
-  _pendingTotal--;
   const size = s.size;
   if (size === 0) {
     pendingByName.delete(name);
   }
   batch(() => {
     pendingSigs.ensure(name, 0).value = size;
-    pendingTotalSig.value = _pendingTotal;
+    pendingTotalSig.value = inflight.size;
   });
 }
 
-function compact(): void {
-  while (_head < log.length && log[_head] === null) {
-    _head++;
+/** Bound `settled` by evicting the lowest-seq (first-record order) entry —
+ *  the same victim the old array shape's oldest-position-first scan picked.
+ *  Map insertion order alone is settle order, not first-record order (a
+ *  long-pending dispatch settles late), hence the ≤ (MAX_LOG_SIZE + 1)-entry
+ *  scan. `protectId` shields the entry being recorded right now — load-
+ *  bearing on the pending → terminal path (a long-lived pending that finally
+ *  settles carries the lowest seq of the whole log and would otherwise evict
+ *  itself the instant it completed; the old shape's own-id guard covered
+ *  this). On the terminal-only path it is belt-and-braces: a fresh seq is
+ *  never the lowest among older entries. */
+function evictOldestSettled(protectId: string): void {
+  while (settled.size > MAX_LOG_SIZE) {
+    let oldestKey: string | undefined;
+    let oldestSeq = Infinity;
+    for (const [key, entry] of settled) {
+      if (key !== protectId && entry.seq < oldestSeq) {
+        oldestSeq = entry.seq;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey === undefined) {
+      return;
+    }
+    settled.delete(oldestKey);
+  }
+}
+
+/** Reclaim the oldest in-flight entry once the table exceeds MAX_INFLIGHT,
+ *  skipping `protectId` (the entry being recorded right now must not reclaim
+ *  itself — a revived entry keeps its original, possibly-lowest seq). The
+ *  reclaimed entry is dropped outright (not moved to `settled`: its status is
+ *  still "pending", and the terminal log must not lie). Runs on every path
+ *  that grows the table: unknown-pending insert AND terminal → pending
+ *  revival. */
+function reclaimLeakedPending(protectId: string): void {
+  if (inflight.size <= MAX_INFLIGHT) {
+    return;
   }
-  if (_head > 256) {
-    log.splice(0, _head);
-    for (const entry of idMap.values()) {
-      entry.index -= _head;
+  let oldestKey: string | undefined;
+  let oldestSeq = Infinity;
+  for (const [key, entry] of inflight) {
+    if (key !== protectId && entry.seq < oldestSeq) {
+      oldestSeq = entry.seq;
+      oldestKey = key;
     }
-    _head = 0;
+  }
+  if (oldestKey === undefined) {
+    return;
+  }
+  const entry = inflight.get(oldestKey);
+  inflight.delete(oldestKey);
+  if (entry !== undefined) {
+    unindexPending(entry.instance.name, oldestKey);
+    console.warn(
+      `[actions] in-flight capacity exceeded (${String(MAX_INFLIGHT)} entries) — reclaiming oldest pending "${entry.instance.name}" (${oldestKey}). Check for dispatches that never settle.`,
+    );
   }
 }
 
 /** Record a state transition. Called by define.ts. */
 export function record(instance: ActionInstance): void {
-  const existing = idMap.get(instance.id);
-  if (existing !== undefined) {
-    const prev = existing.instance;
-    if (prev.status === "pending" && instance.status !== "pending") {
-      removePending(prev.name, instance.id);
-    } else if (prev.status !== "pending" && instance.status === "pending") {
-      addPending(instance.name, instance.id);
-    }
-    log[existing.index] = instance;
-    existing.instance = instance;
-    if (instance.status !== "pending" && _liveCount > MAX_LOG_SIZE) {
-      for (let i = _head; i < log.length; i++) {
-        const entry = log[i];
-        if (
-          entry !== null &&
-          entry !== undefined &&
-          entry.status !== "pending" &&
-          entry.id !== instance.id
-        ) {
-          idMap.delete(entry.id);
-          log[i] = null;
-          _liveCount--;
-          if (_liveCount <= MAX_LOG_SIZE) {
-            break;
-          }
-        }
+  const { id } = instance;
+  if (instance.status === "pending") {
+    const inf = inflight.get(id);
+    if (inf !== undefined) {
+      // Pending re-record: in-place overwrite, no accounting change.
+      inf.instance = instance;
+    } else {
+      const done = settled.get(id);
+      if (done !== undefined) {
+        // Terminal → pending re-record. Not produced by define.ts (one
+        // pending, then at most one terminal per id); defined anyway: move
+        // back, keep the original seq. Grows the table, so the watchdog
+        // runs here too (protecting the revived id itself).
+        settled.delete(id);
+        done.instance = instance;
+        inflight.set(id, done);
+        indexPending(instance.name, id);
+        reclaimLeakedPending(id);
+      } else {
+        seqCounter += 1;
+        inflight.set(id, { instance, seq: seqCounter });
+        indexPending(instance.name, id);
+        reclaimLeakedPending(id);
       }
-      compact();
     }
   } else {
-    const idx = log.length;
-    log.push(instance);
-    idMap.set(instance.id, { instance, index: idx });
-    _liveCount++;
-    if (instance.status === "pending") {
-      addPending(instance.name, instance.id);
-    }
-    if (_liveCount > MAX_LOG_SIZE) {
-      for (let i = _head; i < log.length; i++) {
-        const entry = log[i];
-        if (entry !== null && entry !== undefined && entry.status !== "pending") {
-          idMap.delete(entry.id);
-          log[i] = null;
-          _liveCount--;
-          break;
-        }
-      }
-    }
-    if (_liveCount > MAX_LOG_HARD) {
-      for (let i = _head; i < log.length; i++) {
-        const entry = log[i];
-        if (entry !== null && entry !== undefined) {
-          if (entry.status === "pending") {
-            removePending(entry.name, entry.id);
-          }
-          idMap.delete(entry.id);
-          log[i] = null;
-          _liveCount--;
-          break;
-        }
+    const inf = inflight.get(id);
+    if (inf !== undefined) {
+      // The common transition: pending → terminal. Membership moves between
+      // the tables; the accounting decrements because the id LEFT inflight,
+      // not because a counter was paired correctly. Order matters: the
+      // entry is FULLY moved (settled + evicted) before unindexPending
+      // publishes signals, because reactive effects flush synchronously at
+      // that batch's end — an observer reading getActionLog()/pendingCount
+      // there must see the entry as terminal, never absent, and a reentrant
+      // same-id record from an effect must find it in `settled` (the revive
+      // cell) rather than minting a duplicate wrapper.
+      const indexedName = inf.instance.name;
+      inflight.delete(id);
+      inf.instance = instance;
+      settled.set(id, inf);
+      evictOldestSettled(id);
+      unindexPending(indexedName, id);
+    } else {
+      const done = settled.get(id);
+      if (done !== undefined) {
+        // Double-terminal record: latest-per-id, keep seq + position.
+        done.instance = instance;
+      } else {
+        // Terminal-only record (cancelled before start, optimistic failure).
+        seqCounter += 1;
+        settled.set(id, { instance, seq: seqCounter });
+        evictOldestSettled(id);
       }
     }
-    compact();
-  }
-  if (_pendingTotal < 0) {
-    if (_throwOnInvariantViolation) {
-      throw new Error("[actions] _pendingTotal went negative — invariant violation");
-    }
-    console.warn("[actions] _pendingTotal went negative — invariant violation; clamping to 0");
-    _pendingTotal = 0;
-    pendingTotalSig.value = 0;
   }
   for (const fn of listeners) {
     try {
@@ -211,23 +273,20 @@ export function subscribeByName(name: string, fn: RegistryListener): () => void
 
 /** @internal Test-only public surface. */
 export function recentLog(): readonly ActionInstance[] {
-  const result: ActionInstance[] = [];
-  for (let i = _head; i < log.length; i++) {
-    const entry = log[i];
-    if (entry != null) {
-      result.push(entry);
-    }
-  }
-  return result;
+  const entries = [...inflight.values(), ...settled.values()];
+  entries.sort((a, b) => a.seq - b.seq);
+  return entries.map((e) => e.instance);
 }
 
 /** Read the recent action log. Useful for devtools integration and
  *  debugging panels. Returns a snapshot of all live entries.
  *
- *  SECURITY/PRIVACY: each entry retains the full dispatch `args` in memory (up to
- *  MAX_LOG_SIZE entries), `subscribeToActions` fans `args` out to every listener, and
- *  buildRetryButton retains a structuredClone of `args` in the error-notification
- *  retry closure. Do NOT put secrets, tokens, or PII in action args. */
+ *  SECURITY/PRIVACY: each entry retains the full dispatch `args` in memory (up
+ *  to MAX_LOG_SIZE settled entries plus every in-flight dispatch, watchdog-
+ *  bounded at MAX_INFLIGHT), `subscribeToActions` fans `args` out to every
+ *  listener, and buildRetryButton retains a structuredClone of `args` in the
+ *  error-notification retry closure. Do NOT put secrets, tokens, or PII in
+ *  action args. */
 export const getActionLog = recentLog;
 
 /** O(1) check: true if at least one instance of the named action is pending.
@@ -250,34 +309,12 @@ export function pendingCount(names?: readonly string[]): number {
 
 /** Test-only: clear log + listeners. */
 export function _resetForTest(): void {
-  log.length = 0;
-  _head = 0;
-  _liveCount = 0;
-  idMap.clear();
+  inflight.clear();
+  settled.clear();
+  seqCounter = 0;
   pendingByName.clear();
   listeners.clear();
   namedListeners.clear();
-  _pendingTotal = 0;
-  _throwOnInvariantViolation = false;
   pendingSigs.clearAll();
   pendingTotalSig.value = 0;
 }
-
-/**
- * @internal Test-only: toggle whether a detected `_pendingTotal` underflow
- * throws (true) instead of the production warn + clamp (false). Lets tests
- * assert that an add/removePending pairing bug surfaces loudly. Reset to false
- * by `_resetForTest`.
- */
-export function _setThrowOnInvariantViolationForTest(enabled: boolean): void {
-  _throwOnInvariantViolation = enabled;
-}
-
-/**
- * @internal Test-only: simulate an unpaired `removePending` (an add/remove
- * mismatch) by decrementing the pending total without a matching add, driving
- * the invariant negative. The next `record()` then hits the clamp branch.
- */
-export function _forcePendingUnderflowForTest(): void {
-  _pendingTotal--;
-}

package/src/transport.ts

@@ -31,6 +31,11 @@ export type TransportSendFn = (
   opts: { signal: AbortSignal },
 ) => Promise<TransportSendResult>;
 
+/** Command field name carrying the per-dispatch idempotency key injected by
+ *  {@link transportAction}. Exported so consumer-authored custom runners can
+ *  share the wire convention instead of hand-copying the literal. */
+export const IDEMPOTENCY_COMMAND_FIELD = "idempotency_key";
+
 let _send: TransportSendFn | undefined;
 
 /**
@@ -82,7 +87,7 @@ export function transportAction<TArgs, TOp = unknown>(
       const raw = command(args);
       let cmd: TransportCommand;
       if (ctx?.idempotencyKey !== undefined) {
-        cmd = { ...raw, idempotency_key: ctx.idempotencyKey };
+        cmd = { ...raw, [IDEMPOTENCY_COMMAND_FIELD]: ctx.idempotencyKey };
       } else {
         cmd = raw;
       }

package/src/types.ts

@@ -157,6 +157,16 @@ export interface Action<TArgs, TResult> {
   cancel(): void;
 }
 
+/** Typed terminal outcome of a single dispatch, resolved by
+ *  {@link DispatchHandle.outcome}. Distinguishes the three states the
+ *  handle's own `TResult | null` resolution collapses: success (including a
+ *  legitimate `null` / `undefined` result), failure (carrying the normalized
+ *  error), and cancellation. */
+export type ActionOutcome<TResult> =
+  | { readonly status: "success"; readonly value: TResult; readonly attempts?: number }
+  | { readonly status: "error"; readonly error: ActionErrorLike; readonly attempts?: number }
+  | { readonly status: "cancelled" };
+
 /** Handle returned by dispatch(). An augmented Promise with an abort()
  *  method for per-dispatch cancellation (mirrors RTK createAsyncThunk).
  *  Can be awaited directly as a Promise. */
@@ -164,6 +174,12 @@ export interface DispatchHandle<TResult> extends Promise<TResult | null> {
   /** Abort this specific dispatch. Other in-flight dispatches of the
    *  same action are unaffected. Mirrors RTK's promise.abort(). */
   abort(): void;
+  /** Opt-in typed terminal outcome. Resolves alongside the handle (it never
+   *  rejects) with a discriminated {@link ActionOutcome}, letting a caller
+   *  distinguish a legitimate `null` result from failure or cancellation
+   *  without wiring callbacks. The never-rejecting `TResult | null`
+   *  resolution and the callback tiers remain the canonical surface. */
+  readonly outcome: Promise<ActionOutcome<TResult>>;
 }
 
 /** Per-dispatch overrides. */
@@ -189,7 +205,14 @@ export type RequestSpec =
   | {
       readonly method: "POST" | "PUT" | "PATCH" | "DELETE";
       readonly path: string;
+      /** JSON-encoded request body. Mutually exclusive with `rawBody`. */
       readonly body?: unknown;
+      /** Pre-encoded request body, sent as-is with NO JSON encoding and NO
+       *  automatic Content-Type — set the type via `headers` (e.g. a YAML
+       *  document with `Content-Type: text/yaml`). The request() function is
+       *  the encoder seam: compute the encoded payload there per dispatch.
+       *  Mutually exclusive with `body`. */
+      readonly rawBody?: BodyInit;
       readonly headers?: Readonly<Record<string, string>>;
     };