@civitai/blocks-react 0.62.0 → 0.63.1

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -411,6 +411,28 @@ export interface SubmitWorkflowOptions extends ConsentRetryOptions {
      * here — yours, or the one `submit()` mints — is the value BOTH of its
      * attempts carry. So an error you receive may already be a second attempt's;
      * if you then retry a third time by hand, reuse this key for that too.
+     *
+     * 🔴 **FORMAT: `^[A-Za-z0-9_-]{1,64}$` — letters, digits, `_` and `-` only, at
+     * most 64 characters, and NO COLONS.** The host rejects anything else before
+     * the procedure runs: `BAD_REQUEST` / **400** on `blocks.submitWorkflow`, with
+     * `{"code":"invalid_format","pattern":"/^[A-Za-z0-9_-]{1,64}$/","path":["idempotencyKey"]}`.
+     * So a composite key like `sheetId:panelId:nonce` fails every time — that is
+     * the exact value that broke a shipped app, with 201 local tests green. The
+     * colon is excluded deliberately, not cosmetically: the host composes its
+     * per-`(user, app, key)` dedupe key with `:` as the delimiter and relies on the
+     * key being colon-free for that to stay injective. The 64 bound is derived
+     * from the orchestrator's 128-char `externalId` ceiling, which the host builds
+     * by substringing this key.
+     *
+     * 🔴 A key that fails this is **REFUSED before anything is sent**, with
+     * `InvalidIdempotencyKeyError` — nothing was sent and nothing was spent, which
+     * is why it is NOT a {@link WorkflowSubmitError} (every code on that class is
+     * money-ambiguous by design). The key is never sanitised for you: rewriting an
+     * idempotency key would break the identity it exists to carry — two distinct
+     * logical submits could collapse onto one slot, or a retry could be normalised
+     * differently from its first attempt and mint a SECOND reservation. Validate
+     * with `isValidBlockIdempotencyKey` from `@civitai/app-sdk/blocks` if you
+     * compose keys dynamically.
      */
     idempotencyKey?: string;
 }

package/dist/hooks/useBuzzWorkflow.js

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
 import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
-import { generateIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
+import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
 /**
  * The consent-gated scope {@link UseBuzzWorkflow.submit} requires.
  *
@@ -730,7 +730,15 @@ export function useBuzzWorkflow() {
         // them to ONE reservation. Move this line inside `submitOnce` and an
         // automatic retry double-reserves a real person's Buzz — the single
         // regression this feature exists to not have.
-        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+        // 🔴 A CALLER-SUPPLIED KEY IS VALIDATED HERE, AND REFUSED — NOT SANITISED.
+        // The host rejects anything outside `^[A-Za-z0-9_-]{1,64}$` with a 400
+        // before `blocks.submitWorkflow` runs, so an unchecked key is a guaranteed
+        // production failure that no local test used to be able to see. Refusing
+        // before the send is also what makes the money claim unambiguous: see
+        // `InvalidIdempotencyKeyError` for why this cannot be a
+        // `WorkflowSubmitError` (that class's `'exception'` arm explicitly admits
+        // money may have moved; here nothing left the iframe).
+        const idempotencyKey = resolveIdempotencyKey('useBuzzWorkflow.submit', options?.idempotencyKey);
         try {
             return await withConsentRetry(getTransport(), WORKFLOW_SCOPES, () => submitOnce(body, idempotencyKey), options, 
             // Rule 3 in the time axis — see `mountedRef` above for why this hook

package/dist/hooks/useGoodPurchase.d.ts

@@ -19,6 +19,19 @@ export interface GoodPurchaseOptions extends ConsentRetryOptions {
      * when RETRYING a purchase whose response was lost (timeout / network drop)
      * so the server replays the first terminal result instead of charging twice.
      * Omit → a fresh key per `purchase()` call.
+     *
+     * 🔴 **FORMAT: `^[A-Za-z0-9_-]{1,64}$` — letters, digits, `_` and `-` only, at
+     * most 64 characters, and NO COLONS.** `/api/v1/blocks/goods/purchase` rejects
+     * anything else with a **400** (`"Invalid request body"` + a zod `flatten()` in
+     * `details`), so a composite key like `good:extra-slots:1` fails every time.
+     *
+     * 🔴 A key that fails this is **REFUSED before the POST**, with
+     * `InvalidIdempotencyKeyError` — nothing is sent and nothing is spent, and it
+     * is NOT a {@link GoodPurchaseRefusal} (that would assert the server
+     * considered and declined the purchase, which never happened). The key is
+     * never sanitised for you: rewriting an idempotency key would break the
+     * identity it exists to carry. Validate with `isValidBlockIdempotencyKey` from
+     * `@civitai/app-sdk/blocks` if you compose keys dynamically.
      */
     idempotencyKey?: string;
     /**

package/dist/hooks/useGoodPurchase.js

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
 import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
-import { generateIdempotencyKey } from '../transport/transport.js';
+import { resolveIdempotencyKey } from '../transport/transport.js';
 import { useBlockToken } from './useBlockToken.js';
 import { useBuzzPurchase } from './useBuzzPurchase.js';
 import { useHostOrigin } from './useHostOrigin.js';
@@ -252,7 +252,10 @@ export function useGoodPurchase() {
         // value, so however many attempts a single `purchase()` makes, the server
         // sees ONE logical purchase. Moving it inside either closure turns an
         // automatic retry into a second charge.
-        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+        // 🔴 VALIDATED AND REFUSED, NOT SANITISED — see
+        // `InvalidIdempotencyKeyError`. `/api/v1/blocks/goods/purchase` enforces
+        // the same `^[A-Za-z0-9_-]{1,64}$` as the submit and tip paths.
+        const idempotencyKey = resolveIdempotencyKey('useGoodPurchase.purchase', options?.idempotencyKey);
         try {
             return await withConsentRetry(getTransport(), GOOD_PURCHASE_SCOPES, async () => {
                 try {

package/dist/hooks/useTip.d.ts

@@ -13,6 +13,20 @@ export interface TipOptions extends ConsentRetryOptions {
      * RETRYING a tip whose response was lost (timeout / network drop) so the host
      * collapses it to ONE transfer instead of DOUBLE-TIPPING. Omit → the hook mints
      * a fresh key per `tip()` call (each call is a new logical tip).
+     *
+     * 🔴 **FORMAT: `^[A-Za-z0-9_-]{1,64}$` — letters, digits, `_` and `-` only, at
+     * most 64 characters, and NO COLONS.** `/api/v1/blocks/tip` rejects anything
+     * else with a **400** (`"Invalid request body"` + a zod `flatten()` in
+     * `details`), so a composite key like `user:image:nonce` fails every time. The
+     * colon is excluded deliberately, not cosmetically: the host composes its
+     * per-`(user, app, key)` tip dedupe key with `:` as the delimiter and relies on
+     * the key being colon-free for that to stay injective.
+     *
+     * 🔴 A key that fails this is **REFUSED before the POST**, with
+     * `InvalidIdempotencyKeyError` — nothing is sent and nothing is spent. It is
+     * never sanitised for you: rewriting an idempotency key would break the
+     * identity it exists to carry. Validate with `isValidBlockIdempotencyKey` from
+     * `@civitai/app-sdk/blocks` if you compose keys dynamically.
      */
     idempotencyKey?: string;
 }
@@ -54,10 +68,37 @@ export interface UseTip {
  * timeout safe (the server replays the first terminal result). Omitting it mints
  * a fresh key per call, so each call is a distinct logical tip.
  *
+ * 🔴 THE KEY'S FORMAT IS CONSTRAINED — see
+ * {@link TipOptions.idempotencyKey}. Letters, digits, `_` and `-` only, at most
+ * 64 characters, **no colons**; the host 400s anything else, and this hook now
+ * refuses it before the POST.
+ *
+ * 🔴 THIS EXAMPLE USED TO RECOMMEND `React.useId()`, AND THAT WAS A LIVE DEFECT:
+ * `useId()` wraps its value in characters outside the allowed class on most of
+ * the React versions this package's peer range admits (`^18.0.0 || ^19.0.0`) —
+ * React 18.3.1 returns `":R0:"` and early React 19 a guillemet-wrapped id, both
+ * of which 400. (React 19.2.6, resolved in this repo today, happens to return
+ * `_r_0_`, which does clear the charset — so the bug was INVISIBLE here while
+ * being guaranteed for a consumer on 18.) Anyone copying that line shipped a
+ * guaranteed rejection. Prefer a stable id you already have, which is also
+ * better idempotency: it is tied to the THING being tipped rather than to a
+ * component instance, so it survives a remount.
+ *
  * @example
  * const { tip, loading, error } = useTip();
- * const key = React.useId(); // stable across this component's retries
+ * // A stable id from your own data — the best key, because it identifies the
+ * // logical tip rather than the component that rendered it.
+ * const key = `tip-${imageId}-${amount}`;
  * await tip({ toUserId: 123, amount: 50, entityType: 'Image', entityId: 99 }, { idempotencyKey: key });
+ *
+ * @example
+ * // No natural id to hand? Mint one with the SDK's generator and persist it
+ * // for as long as the logical tip lives. Do NOT post-process `useId()` into
+ * // shape: rewriting a key is exactly what this SDK refuses to do, because a
+ * // silently-rewritten key breaks the identity the key exists to carry.
+ * import { generateIdempotencyKey } from '@civitai/blocks-react';
+ * const keyRef = React.useRef(generateIdempotencyKey());
+ * await tip({ toUserId: 123, amount: 50 }, { idempotencyKey: keyRef.current });
  */
 export declare function useTip(): UseTip;
 //# sourceMappingURL=useTip.d.ts.map

package/dist/hooks/useTip.js

@@ -4,7 +4,7 @@ import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
-import { generateIdempotencyKey } from '../transport/transport.js';
+import { resolveIdempotencyKey } from '../transport/transport.js';
 /** The consent-gated scope a tip needs (`social:tip:self`). */
 const TIP_SCOPES = [BLOCK_SCOPES.SOCIAL_TIP_SELF];
 /**
@@ -27,10 +27,37 @@ const TIP_REQUEST_TIMEOUT_MS = 30_000;
  * timeout safe (the server replays the first terminal result). Omitting it mints
  * a fresh key per call, so each call is a distinct logical tip.
  *
+ * 🔴 THE KEY'S FORMAT IS CONSTRAINED — see
+ * {@link TipOptions.idempotencyKey}. Letters, digits, `_` and `-` only, at most
+ * 64 characters, **no colons**; the host 400s anything else, and this hook now
+ * refuses it before the POST.
+ *
+ * 🔴 THIS EXAMPLE USED TO RECOMMEND `React.useId()`, AND THAT WAS A LIVE DEFECT:
+ * `useId()` wraps its value in characters outside the allowed class on most of
+ * the React versions this package's peer range admits (`^18.0.0 || ^19.0.0`) —
+ * React 18.3.1 returns `":R0:"` and early React 19 a guillemet-wrapped id, both
+ * of which 400. (React 19.2.6, resolved in this repo today, happens to return
+ * `_r_0_`, which does clear the charset — so the bug was INVISIBLE here while
+ * being guaranteed for a consumer on 18.) Anyone copying that line shipped a
+ * guaranteed rejection. Prefer a stable id you already have, which is also
+ * better idempotency: it is tied to the THING being tipped rather than to a
+ * component instance, so it survives a remount.
+ *
  * @example
  * const { tip, loading, error } = useTip();
- * const key = React.useId(); // stable across this component's retries
+ * // A stable id from your own data — the best key, because it identifies the
+ * // logical tip rather than the component that rendered it.
+ * const key = `tip-${imageId}-${amount}`;
  * await tip({ toUserId: 123, amount: 50, entityType: 'Image', entityId: 99 }, { idempotencyKey: key });
+ *
+ * @example
+ * // No natural id to hand? Mint one with the SDK's generator and persist it
+ * // for as long as the logical tip lives. Do NOT post-process `useId()` into
+ * // shape: rewriting a key is exactly what this SDK refuses to do, because a
+ * // silently-rewritten key breaks the identity the key exists to carry.
+ * import { generateIdempotencyKey } from '@civitai/blocks-react';
+ * const keyRef = React.useRef(generateIdempotencyKey());
+ * await tip({ toUserId: 123, amount: 50 }, { idempotencyKey: keyRef.current });
  */
 export function useTip() {
     const host = useHostOrigin();
@@ -149,7 +176,13 @@ export function useTip() {
         // 🔴 MINTED ONCE, OUTSIDE the closure the consent retry re-invokes, so
         // both POSTs carry the SAME key and the host collapses them to ONE
         // transfer. Minting it inside would DOUBLE-TIP a real person.
-        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+        // 🔴 VALIDATED AND REFUSED, NOT SANITISED — see
+        // `InvalidIdempotencyKeyError`. `/api/v1/blocks/tip` enforces the same
+        // `^[A-Za-z0-9_-]{1,64}$` the submit path does, and the tip endpoint's
+        // redis key composes `<userId>:<appBlockId>:<key>` with ':' as the
+        // delimiter, so a colon-bearing key is an injectivity hazard and not just
+        // a format violation.
+        const idempotencyKey = resolveIdempotencyKey('useTip.tip', options?.idempotencyKey);
         try {
             return await withConsentRetry(getTransport(), TIP_SCOPES, () => postTipOnce(params, idempotencyKey), options, 
             // 🔴 RULE 3 IN THE TIME AXIS, AND IT IS NOT COVERED BY THE UNMOUNT

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { BlockTransportDetector, readAllowedOriginsFromEnv } from './transport/d
 export type { DetectOptions } from './transport/detector.js';
 export { getTransport } from './transport/singleton.js';
 export { sendTypedRequest } from './transport/transport.js';
+export { generateIdempotencyKey } from './transport/transport.js';
 export type { BlockSnapshot, BlockTransport, OutboundRequest, } from './transport/transport.js';
 export { useBlockContext } from './hooks/useBlockContext.js';
 export type { UseBlockContext } from './hooks/useBlockContext.js';
@@ -61,6 +62,7 @@ export type { UseGatedImages } from './hooks/useGatedImages.js';
 export { useSaveImage } from './hooks/useSaveImage.js';
 export type { UseSaveImage, SaveImageInput } from './hooks/useSaveImage.js';
 export { RequestTimeoutError } from './transport/transport.js';
+export { InvalidIdempotencyKeyError } from './transport/transport.js';
 export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_CODES, isCollectionFollowErrorCode, } from './hooks/useCollectionFollow.js';
 export type { UseCollectionFollow } from './hooks/useCollectionFollow.js';
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';

package/dist/index.js

@@ -17,6 +17,13 @@ export { InlineTransport } from './transport/inlineTransport.js';
 export { BlockTransportDetector, readAllowedOriginsFromEnv } from './transport/detector.js';
 export { getTransport } from './transport/singleton.js';
 export { sendTypedRequest } from './transport/transport.js';
+// Exported so a block can MINT a conforming key for a logical operation it has
+// no natural id for, and hold it across retries. Previously internal, which is
+// why `useTip`'s own `@example` reached for `React.useId()` instead — a value
+// that fails the host's charset on most of the React versions this package's
+// peer range admits. The documented alternative has to be reachable, or the doc
+// recommends whatever happens to be in scope.
+export { generateIdempotencyKey } from './transport/transport.js';
 // Hooks
 export { useBlockContext } from './hooks/useBlockContext.js';
 export { useBlockTheme } from './hooks/useBlockTheme.js';
@@ -45,6 +52,11 @@ export { useSaveImage } from './hooks/useSaveImage.js';
 // JSDoc says consumers need to distinguish "no reply" from "the host said no" —
 // which they cannot do if they cannot name the type.
 export { RequestTimeoutError } from './transport/transport.js';
+// Exported because all three money hooks can throw it and its whole purpose is
+// to be DISTINGUISHABLE from the money-ambiguous rejections beside it — a caller
+// that cannot name the type cannot tell "nothing was spent" from "may have been
+// spent", which is the one distinction the class exists to carry.
+export { InvalidIdempotencyKeyError } from './transport/transport.js';
 export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_CODES, isCollectionFollowErrorCode, } from './hooks/useCollectionFollow.js';
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';

package/dist/internal/mockHost.js

@@ -40,6 +40,7 @@
 import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED, APP_STORAGE_ERROR_USER_ROW_LIMIT, APP_STORAGE_ERROR_VALUE_TOO_LARGE, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, APP_STORAGE_MAX_VALUE_BYTES, BrowsingLevel, SFW_LEVELS, } from '@civitai/app-sdk/blocks';
 import { consentUnavailablePayload, isKnownBlockScope, resolveUngrantableConsentNotice, } from './consent.js';
 import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, storageScopeDeniedPayload, } from './mockHostScopes.js';
+import { governsIdempotencyKey, idempotencyKeyDeniedMessage, idempotencyKeyRefusal, } from './mockHostIdempotency.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
 /**
@@ -949,6 +950,42 @@ export function createMockHost(options = {}) {
                         return;
                     }
                 }
+                // ---- THE IDEMPOTENCY-KEY FORMAT GATE — see ./mockHostIdempotency.ts ----
+                //
+                // The host's rule is a zod `.regex()` on the procedure INPUT, so it fires
+                // BEFORE the procedure body — ahead of every scenario, budget and balance
+                // decision below. That ordering is the point: a malformed key is refused
+                // even when the scenario, the balance and the spend cap would all have
+                // allowed the submit, because production refuses it then too.
+                //
+                // 🔴 IT SITS AHEAD OF THE SWITCH for the same reason the storage gate
+                // does: one rule covering every surface, so a future money message that
+                // gains an `idempotencyKey` is governed by joining the table rather than
+                // by someone remembering to copy a check into its handler.
+                {
+                    const refusal = governsIdempotencyKey(typed.type)
+                        ? idempotencyKeyRefusal(typed.payload)
+                        : null;
+                    if (refusal !== null) {
+                        dispatchToBlock({
+                            type: 'WORKFLOW_SUBMITTED',
+                            payload: {
+                                requestId,
+                                // The host's `errorSnapshot()` shape exactly (liveHost.ts:298):
+                                // the 'failed' sentinel id and NO `cost`, which is what makes
+                                // `submit()` reject as `'exception'` rather than resolving a
+                                // priced refusal. A tRPC input rejection reaches the block this
+                                // way, not as a throw — the reply crosses postMessage.
+                                snapshot: {
+                                    workflowId: 'failed',
+                                    status: 'failed',
+                                    error: idempotencyKeyDeniedMessage(refusal),
+                                },
+                            },
+                        });
+                        return;
+                    }
+                }
                 switch (typed.type) {
                     case 'REQUEST_TOKEN':
                         dispatchToBlock({

package/dist/internal/mockHostIdempotency.d.ts

@@ -0,0 +1,100 @@
+/**
+ * mockHostIdempotency.ts — the dev host's IDEMPOTENCY-KEY FORMAT GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-02). A character-sheet block sent an
+ * `idempotencyKey` of the form `sheetId:panelId:nonce`. It passed **201 local
+ * tests**, the dev harness and review. Every save in production failed:
+ *
+ *     { "code": "invalid_format", "format": "regex",
+ *       "pattern": "/^[A-Za-z0-9_-]{1,64}$/",
+ *       "path": ["idempotencyKey"],
+ *       "message": "Invalid string: must match pattern /^[A-Za-z0-9_-]{1,64}$/" }
+ *
+ * `BAD_REQUEST` / httpStatus 400 on path `blocks.submitWorkflow`.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE — the exact shape of
+ * #511's storage-scope gap, one surface over. `createMockHost` had **zero**
+ * occurrences of `idempotencyKey`: it accepted the field, forwarded nothing, and
+ * validated nothing, so the one submit failure mode that actually ships was the
+ * only one the mock could not produce. It models a caught server exception, a
+ * disallowed account pool, insufficient Buzz, a fail-rate dice roll and an
+ * induced transport failure — and not the input validator that runs before any
+ * of them.
+ *
+ * This is the missing arm of an existing simulation, not a new feature.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and why the refusal has THIS shape.
+ *
+ * The rule is a zod `.regex()` on the procedure INPUT
+ * (`blocks.router.ts:6227`), so it fires **before the procedure body runs** —
+ * ahead of every scenario, budget and balance decision the handler below would
+ * otherwise make. That ordering is modelled deliberately: the gate sits ahead of
+ * the message switch, so a malformed key is refused even when the scenario,
+ * the balance and the spend cap would all have allowed the submit, because
+ * production refuses it then too.
+ *
+ * A tRPC input rejection reaches the block as a host-synthesised failure
+ * snapshot, NOT as a thrown error — the reply crosses `postMessage`.
+ * `internal/liveHost.ts:298` is the mapping: `errorSnapshot(error)` →
+ * `{ workflowId: 'failed', status: 'failed', error }`, with **no `cost`**. That
+ * is byte-for-byte the shape the disallowed-account branch in `mockHost.ts`
+ * already emits, and it is what makes `useBuzzWorkflow().submit` reject with
+ * `WorkflowSubmitError` code `'exception'`. Emitting anything else here — a
+ * priced refusal, a thrown error, a silent drop — would model a host that does
+ * not exist.
+ *
+ * 🔴 ONE MESSAGE TYPE TODAY, AND A TABLE ANYWAY. `SUBMIT_WORKFLOW` is the only
+ * block→host message in `@civitai/app-sdk`'s protocol carrying an
+ * `idempotencyKey` (the tip and good-purchase paths are direct REST POSTs and
+ * never traverse the mock host, so they are covered by the hook-boundary guard
+ * alone — see `resolveIdempotencyKey`). The table is still the right shape: a
+ * future money message that gains the field is governed the moment it joins
+ * `IDEMPOTENT_MESSAGES`, rather than whenever someone remembers to copy a check
+ * into its handler. That is the property #511 bought on the storage side and the
+ * reason its gate sits ahead of the switch.
+ *
+ * 🔴 WHY THIS IS NOT REDUNDANT WITH THE HOOK GUARD. Two independent reachable
+ * paths bypass the hooks: a block may drive the transport directly
+ * (`getTransport().sendRequest({ type: 'SUBMIT_WORKFLOW', … })`, which the
+ * package exports), and the dev harness dispatches hand-built messages. The gate
+ * is also the arm that makes the DEV HARNESS and the TEST SUITE go red, which is
+ * what the original defect needed and did not have: a hook-side throw protects
+ * callers of that hook, while this protects the protocol.
+ */
+/**
+ * Block→host message types whose payload carries an `idempotencyKey` the host
+ * validates. Exported for the ledger test, which fails when the set grows or
+ * shrinks — so a new money message cannot join the protocol ungated and a
+ * retired one cannot leave a dead row behind.
+ */
+export declare const IDEMPOTENT_MESSAGES: readonly string[];
+/** Does this gate govern `type`? */
+export declare function governsIdempotencyKey(type: string): boolean;
+/**
+ * The refusal text, modelled on the server's own `invalid_format` message so a
+ * developer grepping their production logs for the string finds the dev one too.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING and do not render it to a viewer.
+ * It is developer-facing: a malformed key is a defect in the block's code, so
+ * "please try again" is the wrong copy for it — no number of retries fixes it.
+ */
+export declare function idempotencyKeyDeniedMessage(reason: string): string;
+/**
+ * The reason `payload.idempotencyKey` is unacceptable, or `null` to proceed.
+ *
+ * 🔴 AN ABSENT KEY IS VALID AND MUST STAY VALID. The field is optional on the
+ * wire; `undefined` means "no dedupe", which is the ordinary case for every
+ * block that never passes one. Validating absence would refuse almost every
+ * submit in the suite — and would be a FALSE model, since the host's own schema
+ * is `.optional()` on this path.
+ *
+ * Note the asymmetry the host has and this cannot: the REST submit endpoint
+ * (`submit.ts:135`) makes the field REQUIRED. The mock serves the postMessage
+ * bridge, which is the `.optional()` arm, so absence is correct here.
+ */
+export declare function idempotencyKeyRefusal(payload: {
+    idempotencyKey?: unknown;
+} | undefined): string | null;
+//# sourceMappingURL=mockHostIdempotency.d.ts.map

package/dist/internal/mockHostIdempotency.js

@@ -0,0 +1,113 @@
+/**
+ * mockHostIdempotency.ts — the dev host's IDEMPOTENCY-KEY FORMAT GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-02). A character-sheet block sent an
+ * `idempotencyKey` of the form `sheetId:panelId:nonce`. It passed **201 local
+ * tests**, the dev harness and review. Every save in production failed:
+ *
+ *     { "code": "invalid_format", "format": "regex",
+ *       "pattern": "/^[A-Za-z0-9_-]{1,64}$/",
+ *       "path": ["idempotencyKey"],
+ *       "message": "Invalid string: must match pattern /^[A-Za-z0-9_-]{1,64}$/" }
+ *
+ * `BAD_REQUEST` / httpStatus 400 on path `blocks.submitWorkflow`.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE — the exact shape of
+ * #511's storage-scope gap, one surface over. `createMockHost` had **zero**
+ * occurrences of `idempotencyKey`: it accepted the field, forwarded nothing, and
+ * validated nothing, so the one submit failure mode that actually ships was the
+ * only one the mock could not produce. It models a caught server exception, a
+ * disallowed account pool, insufficient Buzz, a fail-rate dice roll and an
+ * induced transport failure — and not the input validator that runs before any
+ * of them.
+ *
+ * This is the missing arm of an existing simulation, not a new feature.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and why the refusal has THIS shape.
+ *
+ * The rule is a zod `.regex()` on the procedure INPUT
+ * (`blocks.router.ts:6227`), so it fires **before the procedure body runs** —
+ * ahead of every scenario, budget and balance decision the handler below would
+ * otherwise make. That ordering is modelled deliberately: the gate sits ahead of
+ * the message switch, so a malformed key is refused even when the scenario,
+ * the balance and the spend cap would all have allowed the submit, because
+ * production refuses it then too.
+ *
+ * A tRPC input rejection reaches the block as a host-synthesised failure
+ * snapshot, NOT as a thrown error — the reply crosses `postMessage`.
+ * `internal/liveHost.ts:298` is the mapping: `errorSnapshot(error)` →
+ * `{ workflowId: 'failed', status: 'failed', error }`, with **no `cost`**. That
+ * is byte-for-byte the shape the disallowed-account branch in `mockHost.ts`
+ * already emits, and it is what makes `useBuzzWorkflow().submit` reject with
+ * `WorkflowSubmitError` code `'exception'`. Emitting anything else here — a
+ * priced refusal, a thrown error, a silent drop — would model a host that does
+ * not exist.
+ *
+ * 🔴 ONE MESSAGE TYPE TODAY, AND A TABLE ANYWAY. `SUBMIT_WORKFLOW` is the only
+ * block→host message in `@civitai/app-sdk`'s protocol carrying an
+ * `idempotencyKey` (the tip and good-purchase paths are direct REST POSTs and
+ * never traverse the mock host, so they are covered by the hook-boundary guard
+ * alone — see `resolveIdempotencyKey`). The table is still the right shape: a
+ * future money message that gains the field is governed the moment it joins
+ * `IDEMPOTENT_MESSAGES`, rather than whenever someone remembers to copy a check
+ * into its handler. That is the property #511 bought on the storage side and the
+ * reason its gate sits ahead of the switch.
+ *
+ * 🔴 WHY THIS IS NOT REDUNDANT WITH THE HOOK GUARD. Two independent reachable
+ * paths bypass the hooks: a block may drive the transport directly
+ * (`getTransport().sendRequest({ type: 'SUBMIT_WORKFLOW', … })`, which the
+ * package exports), and the dev harness dispatches hand-built messages. The gate
+ * is also the arm that makes the DEV HARNESS and the TEST SUITE go red, which is
+ * what the original defect needed and did not have: a hook-side throw protects
+ * callers of that hook, while this protects the protocol.
+ */
+import { BLOCK_IDEMPOTENCY_KEY_REGEX, blockIdempotencyKeyRejection, } from '@civitai/app-sdk/blocks';
+/**
+ * Block→host message types whose payload carries an `idempotencyKey` the host
+ * validates. Exported for the ledger test, which fails when the set grows or
+ * shrinks — so a new money message cannot join the protocol ungated and a
+ * retired one cannot leave a dead row behind.
+ */
+export const IDEMPOTENT_MESSAGES = ['SUBMIT_WORKFLOW'];
+/** Does this gate govern `type`? */
+export function governsIdempotencyKey(type) {
+    return IDEMPOTENT_MESSAGES.includes(type);
+}
+/**
+ * The refusal text, modelled on the server's own `invalid_format` message so a
+ * developer grepping their production logs for the string finds the dev one too.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING and do not render it to a viewer.
+ * It is developer-facing: a malformed key is a defect in the block's code, so
+ * "please try again" is the wrong copy for it — no number of retries fixes it.
+ */
+export function idempotencyKeyDeniedMessage(reason) {
+    // 🔴 INTERPOLATED FROM THE VENDORED CONSTANT, NEVER RE-TYPED. The first draft
+    // of this line spelled the pattern out — and the single-source guard
+    // (`tests/guards/idempotency-key-rule-single-source.test.mjs`) caught it,
+    // which is the whole point of that guard: a second copy of a rule the host
+    // owns can only ever drift from it.
+    return `Invalid string: must match pattern ${String(BLOCK_IDEMPOTENCY_KEY_REGEX)} (idempotencyKey) — ${reason}`;
+}
+/**
+ * The reason `payload.idempotencyKey` is unacceptable, or `null` to proceed.
+ *
+ * 🔴 AN ABSENT KEY IS VALID AND MUST STAY VALID. The field is optional on the
+ * wire; `undefined` means "no dedupe", which is the ordinary case for every
+ * block that never passes one. Validating absence would refuse almost every
+ * submit in the suite — and would be a FALSE model, since the host's own schema
+ * is `.optional()` on this path.
+ *
+ * Note the asymmetry the host has and this cannot: the REST submit endpoint
+ * (`submit.ts:135`) makes the field REQUIRED. The mock serves the postMessage
+ * bridge, which is the `.optional()` arm, so absence is correct here.
+ */
+export function idempotencyKeyRefusal(payload) {
+    const key = payload?.idempotencyKey;
+    if (key === undefined)
+        return null;
+    return blockIdempotencyKeyRejection(key);
+}
+//# sourceMappingURL=mockHostIdempotency.js.map

package/dist/transport/transport.d.ts

@@ -232,6 +232,63 @@ export declare function nextRequestId(): string;
  * string where it is unavailable (older webviews / non-secure contexts / test).
  */
 export declare function generateIdempotencyKey(): string;
+/**
+ * A CALLER-SUPPLIED `idempotencyKey` that the host would reject. Thrown by
+ * `useBuzzWorkflow().submit`, `useTip().tip` and `useGoodPurchase().purchase`
+ * **before anything is sent**.
+ *
+ * 🔴 NOTHING WAS SENT AND NOTHING WAS SPENT — that is the whole reason this is a
+ * DISTINCT class rather than one of the existing money-path errors. Every other
+ * rejection on these hooks is money-AMBIGUOUS by design:
+ * `WorkflowSubmitError`'s own docs say its `'exception'` arm covers "a lost
+ * response or an in-progress idempotency conflict", and the abort/timeout
+ * rejections say in as many words that "the charge may or may not have landed".
+ * Reusing any of those for a key refused at the boundary would hand the caller
+ * an error whose documented contract is strictly weaker than the truth, and the
+ * repo's money rule runs the other way: never tell a caller money did not move
+ * unless you know it. Here we do know, structurally — the request never left the
+ * iframe — so the caller gets a type that says so.
+ *
+ * Two further reasons it is not a `WorkflowSubmitError`:
+ *   - that class REQUIRES a `snapshot`, which is the host's reply. There is no
+ *     reply. Synthesising one would be inventing a host message the host never
+ *     sent, and `workflowId: 'failed'` specifically means "the host had no
+ *     workflow to report" — a claim about the host we are not entitled to make.
+ *   - it is not a runtime OUTCOME at all. It is a defect in the calling block's
+ *     own code, in the same family as the existing
+ *     `'host origin not established yet'` throw: no retry fixes it, and the fix
+ *     is a source change.
+ *
+ * 🔴 THE KEY IS REFUSED, NEVER REWRITTEN. See `@civitai/app-sdk/blocks`'
+ * `idempotency.ts`: sanitising a caller's key would break the identity the key
+ * exists to carry — two distinct logical submits could collapse onto one slot,
+ * or a retry could be normalised differently from its first attempt and mint a
+ * SECOND reservation. A loud refusal is the only money-safe answer.
+ *
+ * Branch on `instanceof` or `name === 'InvalidIdempotencyKeyError'`; the
+ * `message` wording is developer-facing and is not a contract. Do NOT render it
+ * to a viewer — they cannot act on it.
+ */
+export declare class InvalidIdempotencyKeyError extends Error {
+    /** The rejected value, verbatim, for logging. The block's own construction. */
+    readonly idempotencyKey: unknown;
+    /** Which hook refused it, e.g. `'useBuzzWorkflow.submit'`. */
+    readonly source: string;
+    constructor(source: string, idempotencyKey: unknown, message: string);
+}
+/**
+ * Refuse a caller-supplied key, or mint one when the caller supplied none.
+ *
+ * 🔴 THE `undefined` CASE IS NOT VALIDATED, AND MUST NOT BE. `idempotencyKey` is
+ * optional on all three hooks; absent means "mint one for me", and the generated
+ * key conforms by construction. Routing `undefined` into the predicate would
+ * turn every ordinary keyless call into a refusal.
+ *
+ * Ordering is load-bearing: validation happens BEFORE the generator is consulted
+ * and before any transport/fetch work, so a bad key costs nothing and cannot
+ * race a send.
+ */
+export declare function resolveIdempotencyKey(source: string, supplied: string | undefined): string;
 /**
  * A request that got NO REPLY before its timeout elapsed.
  *