@civitai/blocks-react 0.61.1 → 0.63.0

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.d.ts

@@ -599,18 +599,70 @@ export interface MockHostOptions {
      * {@link MockHost.setScenario}.
      */
     disallowedAccountTypes?: BuzzAccountType[];
+    /**
+     * The scopes the app's `block.manifest.json` DECLARES — the set the real
+     * host's token mint draws from.
+     *
+     * 🔴 **STORAGE IS GATED ON THIS, AND THE DEFAULT IS EMPTY.** A storage op whose
+     * scope is not in here is refused exactly as the server refuses it, because the
+     * server's test is presence in the block's approved scope set (see
+     * `BLOCK_SCOPES` in `@civitai/app-sdk`) and an undeclared scope is never
+     * approved. Omit this and every `APP_STORAGE_*` / `SHARED_*` call fails.
+     *
+     * That is a DELIBERATE BREAKING DEFAULT. Until this existed the mock host
+     * served storage unconditionally, so an app that forgot the scopes passed its
+     * whole suite and the dev harness and then failed every save in production —
+     * the one storage failure mode that actually ships was the only one the mock
+     * could not produce. A default of "permissive" would have left that true for
+     * every app that did not opt in, i.e. precisely the apps that did not know the
+     * scopes existed.
+     *
+     * Pass what your manifest declares — ideally by importing your own
+     * `block.manifest.json` as `manifest`, so the two cannot drift:
+     *
+     * ```ts
+     * createMockHost({ declaredScopes: manifest.scopes });
+     * ```
+     *
+     * ⚠️ The `import` line is described rather than shown ON PURPOSE, and please
+     * do not helpfully add it back. `tests/guards/blocks-react-entry-directory-names.test.mjs`
+     * extracts import specifiers with a raw regex over the whole file —
+     * `/\bfrom\s*['"]([^'"]+)['"]/g`, comments included — so a `from '…'` inside a
+     * doc comment is read as a real edge and resolved against THIS file's
+     * directory. A relative path to a consumer's manifest does not exist from
+     * here, and the guard fails with `unresolvable specifier`. Measured: it went
+     * red on all five `Starter (…)` matrix legs.
+     *
+     * A test that only exercises storage mechanics (quota, caps, row limits) and
+     * does not care about authorization should declare the storage scopes
+     * explicitly rather than reach for a permissive flag — there is none, on
+     * purpose.
+     *
+     * ⚠️ Scopes OTHER than storage are not read from here yet. `ai:write:budgeted`
+     * keeps its own `consentGranted` flag, because `buzzBudget` is conditional on
+     * it and `setScenario` can toggle it mid-session; giving one scope two sources
+     * of truth is how they drift.
+     */
+    declaredScopes?: string[];
     /**
      * STORAGE scenario: in-memory KV backend (seed / quota / failNext). See
      * {@link MockStorageScenario}. When omitted, the store starts EMPTY with the
-     * v0 defaults — `APP_STORAGE_*` is answered either way (the mock host always
-     * serves storage now).
+     * v0 defaults.
+     *
+     * ⚠️ This governs the BACKEND, not authorization. Storage is additionally
+     * gated on {@link MockHostOptions.declaredScopes}, which defaults to empty —
+     * so a scenario alone no longer makes storage answer. (It used to: this doc
+     * said `APP_STORAGE_*` was "answered either way", and that was the defect.)
      */
     storage?: MockStorageScenario;
     /**
      * SHARED scenario: in-memory, app-scoped, votable backend (seed / failNext).
-     * See {@link MockSharedScenario}. When omitted, the shared store starts EMPTY
-     * — the `SHARED_*` protocol is answered either way (the mock host always
-     * serves shared storage now).
+     * See {@link MockSharedScenario}. When omitted, the shared store starts EMPTY.
+     *
+     * ⚠️ As with {@link MockHostOptions.storage}, this governs the BACKEND and not
+     * authorization: `SHARED_*` is additionally gated on
+     * {@link MockHostOptions.declaredScopes} (`apps:storage:shared:read` /
+     * `:write`), which defaults to empty.
      */
     shared?: MockSharedScenario;
     /** Host theme delivered in `BLOCK_INIT` + context. Default `'dark'`. */

package/dist/internal/mockHost.js

@@ -39,6 +39,8 @@
  */
 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';
 /**
@@ -849,6 +851,19 @@ export function createMockHost(options = {}) {
          * precisely what `./consent.js`'s header warns about.
          */
         const extraGrantedScopes = new Set();
+        /**
+         * What the app's manifest DECLARES — the set the real host's token mint draws
+         * from, and the set the storage gate tests presence in.
+         *
+         * 🔴 Deliberately NOT defaulted to anything permissive. See
+         * {@link MockHostOptions.declaredScopes}: a permissive default would leave the
+         * pre-gate behaviour in place for every app that did not opt in, which is the
+         * population the gate exists for.
+         *
+         * This is a SNAPSHOT at install time, unlike `consentGranted`, which
+         * `setScenario` can toggle. A manifest does not change mid-session.
+         */
+        const declaredScopeSet = new Set(options.declaredScopes ?? []);
         /** Everything the CURRENT token carries. One reader, so the two cannot drift. */
         const currentScopes = () => [
             ...(consentGranted ? [BUDGETED_SCOPE] : []),
@@ -911,6 +926,66 @@ export function createMockHost(options = {}) {
                 const typed = msg;
                 options.onOutbound?.({ type: typed.type, payload: typed.payload });
                 const requestId = typed.payload?.requestId;
+                // ---- THE STORAGE SCOPE GATE — see ./mockHostScopes.ts ----
+                //
+                // The server's test is PRESENCE in the block's approved scope set, so an
+                // UNDECLARED scope is refused before the backend is ever consulted. That
+                // ordering is the point: it refuses even when the scenario, the quota and
+                // the row budget would all have allowed the op, because production does.
+                //
+                // 🔴 IT SITS AHEAD OF THE SWITCH SO ONE RULE COVERS EVERY SURFACE. The
+                // alternative — a check inside each of the 15 storage handlers — is the
+                // shape that regenerates the same omission at every new site: a storage
+                // message added later is governed the moment it joins the table in
+                // `mockHostScopes.ts`, rather than whenever someone remembers to copy a
+                // guard into its handler.
+                {
+                    const needed = requiredStorageScope(typed.type);
+                    if (needed !== null && !declaredScopeSet.has(needed)) {
+                        const error = storageScopeDeniedMessage(typed.type, needed);
+                        dispatchToBlock({
+                            type: storageResultType(typed.type),
+                            payload: storageScopeDeniedPayload(typed.type, requestId, error),
+                        });
+                        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