@civitai/blocks-react 0.64.0 → 0.65.1

package/README.md

@@ -325,12 +325,10 @@ if (priced) {
   try {
     const snap = await submit(body); // status 'submitting' → 'polling'
     if (snap.status === 'failed') {
-      // 🔴 A RESOLVED `failed` IS A PRICED SERVER OUTCOME — and only SOME of
-      // them are about the viewer's wallet. Affordability (per-call budget, the
-      // per-user daily Buzz cap) IS fixable by buying Buzz; the per-app velocity
-      // limit, the per-app aggregate daily cap, a fail-closed "temporarily
-      // unavailable" deny and a missing price quote are NOT. Selling Buzz for
-      // one of those takes money and fixes nothing, so branch before you offer.
+      // 🔴 A RESOLVED `failed` IS A SERVER OUTCOME, NEVER A TOP-UP CUE: a spend
+      // cap or limit buying Buzz does not raise, or a run that may already have
+      // spent. The complete list is on `useBuzzWorkflow`'s `submit` docs.
+      // Running OUT of Buzz rejects instead — see the catch below.
       showError(submitOutcomeMessage(snap)); // YOUR app owns this copy
     } else {
       await poll(snap.workflowId);   // you loop this on a backoff until terminal
@@ -375,11 +373,14 @@ if (priced) {
   `status: 'failed'`, an `error` string, **and a numeric `cost.total`** — the
   price the server refused to charge. That is a workflow *outcome*, not an error.
   Check `snap.status`, not just `try/catch`.
-  🔴 **Not all of them are affordability.** Only the per-call `buzzBudget` gate
-  and the per-user daily Buzz cap are about the wallet. The per-app **velocity**
-  limit, the per-app **aggregate daily** cap, a fail-closed **"temporarily
-  unavailable"** deny and a **missing price quote** are priced outcomes too, and
-  buying Buzz fixes none of them. Branch before you offer a top-up.
+  🔴 **None of them is a top-up cue.** Each is a spend cap or limit that buying
+  Buzz does not raise — the per-call `buzzBudget` and the viewer's daily cap
+  included — or a reply that may already have spent. The complete list, and
+  which of them may say "nothing was charged", is in `useBuzzWorkflow`'s
+  `submit` docs. A viewer who is genuinely **out of Buzz** makes `submit`
+  **reject** (`WorkflowSubmitError` code `'exception'`, shared with other
+  thrown submits): decide a top-up from `useBuzzBalance()` — blue plus the
+  block's domain pool, never all three — against the quoted cost.
 - **`submit` REJECTS when the reply carries no usable workflow outcome**
   (`@civitai/blocks-react@0.44.0+`). Every failure-shaped reply reports
   `status: 'failed'`, so `status` cannot tell them apart — **`cost` presence
@@ -468,7 +469,9 @@ if (priced) {
 
 ### `useBuzzPurchase()`
 
-Open the Buzz purchase modal — the insufficient-budget recovery path.
+Open the Buzz purchase modal. It raises the viewer's WALLET, never a spend cap:
+offer it when the viewer's spendable Buzz is below a quoted cost, never on a
+resolved `failed` submit (see `useBuzzWorkflow`'s `submit` docs).
 
 ```tsx
 const { openPurchaseModal } = useBuzzPurchase();
@@ -735,6 +738,126 @@ options drive both arms (including `declined`). **`dev:live` refuses this bridge
 it has no civitai chrome to render the server-resolved confirm in, and driving
 the write without it would let dev prove out a flow production does not have.
 
+### `usePrepareTrainingDataset()` and `useRunTraining()` — LoRA training
+
+Train a LoRA with the ai-toolkit engine on the **viewer's own images**, from
+inside a page app — the App Blocks `kind: 'training'` flow. Four steps, three
+hooks:
+
+1. **Dataset** — `usePrepareTrainingDataset().prepareDataset([{ imageId, caption }])`
+   (`PREPARE_TRAINING_DATASET`). Only the viewer's own scanned, unflagged images
+   within the page's maturity ceiling are admitted; the rest come back in
+   `rejected` with a reason (`unavailable`, `unsupported-media`, `not-eligible`,
+   `pending-scan`, `import-failed`, `import-unavailable`; `pending-scan` and
+   `import-unavailable` are retryable). You get an opaque `datasetId` and the
+   admitted `count`, always at least 1 — if **nothing** is admitted the call
+   rejects with the server's message instead. 1–50 images, captions up to 1,000 characters; captions are
+   moderated. No dialog, no charge.
+2. **Quote** — `useBuzzWorkflow().estimate(body)` with a `WorkflowBodyTraining`
+   (`kind: 'training'`, no `quoteId`). The reply carries `trainingQuote:
+   { quoteId, total, imageCount, expiresAt }` — the orchestrator's own price for
+   exactly this run, stored server-side for 15 minutes.
+3. **Run** — `useRunTraining().runTraining({ ...body, quoteId })` (`RUN_TRAINING`).
+   **Civitai shows the viewer a consent dialog in its own chrome** — price, base
+   model, length and dataset size, all read back from the server, never from
+   your body — and submits only on their click. Change nothing in the body
+   between the estimate and the run; the server checks it against the quoted one.
+4. **Follow** — `useBuzzWorkflow().watch(workflowId)`. Once the run's moderation
+   status is approved, `trainedEpochs` lists the epochs whose checkpoint is
+   ready; send the viewer to the publish wizard with one of them (see
+   `trainedEpochs` on `BlockWorkflowSnapshot`).
+
+🔴 **Availability.** Behind the host flag **`app-blocks-training-kind`**, which
+ships **off** and is evaluated per viewer. **Page apps only** — the model slot
+answers both messages with an error. The manifest must declare
+**`ai:write:budgeted`** and the viewer must be signed in and have granted it.
+**Refused from `dev:live` and from review sessions** (the server refuses
+development and review tokens); build the flow against the mock host. Requires a
+civitai.com host carrying civitai/civitai#5434 (`kind: 'training'`,
+`RUN_TRAINING`) and civitai/civitai#5438 (`PREPARE_TRAINING_DATASET`).
+
+🔴 **Money.** There is no `maxBuzz` and no timeout knob — the price is the quote.
+A confirmed run may cost more than the token's per-call `buzzBudget` (the viewer
+confirms the exact price), up to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz);
+an estimate above that is refused. `useBuzzWorkflow().submit()` **refuses** a
+training body before sending anything: only `RUN_TRAINING`'s dialog can confirm a
+quote, so a training run starts nowhere else.
+
+`runTraining` **rejects** with a `RunTrainingError`; read the flags before
+saying anything about money:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.declined` | the viewer dismissed the dialog — **no run was submitted** | revert, say nothing |
+| `err.unconfirmed` | `submission-unconfirmed`, or no reply within the 10-min bound (`err.timedOut`) — the run **may be running and charged** | 🔴 **never retry automatically**: check the viewer's trainings first (`useAppWorkflows()` lists this app's runs). Re-running the same body after the server did start it is a **second, separately charged run** |
+| `err.refused` (`code: 'refused'`) | the server refused the submit after the viewer confirmed — a **spend cap** (their daily or private-run Buzz cap, the per-app consent budget, the app's daily spend or rate limit, a dev-session cap) or a **temporary-availability** deny. Refunded: **no run, nothing charged**; the quote is used up | show `err.message` (the server's reason, e.g. `daily Buzz cap reached: …`); estimate again before any retry — buying Buzz does not lift these caps |
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `invalid training request` / `no block token`) | show or ignore per case |
+| `err.code === undefined`, no flag | a server refusal before any submit (expired or used quote, changed body, ineligible image) | estimate again, then retry |
+
+`prepareDataset` rejects with a `PrepareTrainingDatasetError` (`.code` for the
+host's refusals — `review-mode`, `block is not ready`, `sign in to train`,
+`invalid training dataset`, `no block token` — plus `.signInRequired` and
+`.timedOut`). Preparing charges nothing, so none of them cost Buzz. It prompts
+for `ai:write:budgeted` and retries once on a grant (see the table below);
+`runTraining` deliberately does not — it carries no idempotency key and has an
+outcome where a run may exist, so it never re-sends.
+
+```tsx
+const { prepareDataset } = usePrepareTrainingDataset();
+const { estimate, watch } = useBuzzWorkflow();
+const { runTraining } = useRunTraining();
+
+async function train(images: Array<{ id: number; caption: string }>) {
+  // Rejects (no `.code`) when NOTHING is admitted, e.g. "none of the requested
+  // images can be used for training"; a resolved dataset always has count >= 1.
+  const dataset = await prepareDataset(images.map((i) => ({ imageId: i.id, caption: i.caption })));
+  if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+
+  const body: WorkflowBodyTraining = {
+    kind: 'training',
+    datasetId: dataset.datasetId,
+    engine: 'ai-toolkit',
+    model: baseModelKey, // a key from Civitai's training catalog
+    params: aiToolkitParams, // AiToolkitTrainingParams
+    triggerWord: 'mystyle',
+    samplePrompts: ['mystyle, a lighthouse at dusk'],
+  };
+  const quote = (await estimate(body)).trainingQuote;
+  if (!quote) return showError('No training price came back.');
+  // Show quote.total; the host's dialog will show the same number.
+
+  try {
+    const started = await runTraining({ ...body, quoteId: quote.quoteId });
+    const done = await watch(started.workflowId, { onUpdate: render });
+    setEpochs(done.trainedEpochs ?? []);
+  } catch (err) {
+    if (!(err instanceof RunTrainingError)) throw err;
+    if (err.declined) return; // no run
+    if (err.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+    if (err.refused) return showError(err.message); // a cap / availability refusal; no run, nothing charged
+    if (err.signInRequired) return requestSignIn();
+    showError('Could not start training. Get a new price and try again.');
+  }
+}
+```
+
+With the mock host — `createMockHost` or `Harness` from
+`@civitai/blocks-react/testing` — the training path is **kind-faithful**: it
+holds the datasets it prepared and the quotes it stored, refuses an unknown
+dataset, a dataset with nothing admitted, a quote above 5,000 and a quote run
+twice, and needs
+`ai:write:budgeted` on the token and a signed-in viewer. Its knobs are
+`trainingDatasetRejected`, `trainingDatasetError`, `trainingQuoteTotal`,
+`runTrainingError` (`'declined'`, `'submission-unconfirmed'`, or any server
+message), `runTrainingCapRefusal` (the server's resolved cap / availability refusal, which consumes the quote →
+`err.refused`) and `generation.trainedEpochs` for the finished run. It has no
+consent dialog, so `runTraining` settles at once where the real host waits on a
+click, and it checks a run's body against its quote by `datasetId` only — the
+server compares the whole body.
+**`dev:live` refuses both bridges**, because the server refuses every training
+request from a dev token.
+
 ### `useAppWorkflows(params?)`
 
 The calling app's **own** generator subqueue — the tag-scoped list of generations
@@ -1227,6 +1350,7 @@ had just worked.
 |---|---|---|
 | `useBuzzWorkflow()` | `submit()` | `ai:write:budgeted` |
 | `useCreatePostFromApp()` | `createPost()` | `posts:write:self` |
+| `usePrepareTrainingDataset()` | `prepareDataset()` | `ai:write:budgeted` |
 | `useGoodPurchase()` | `purchase()` | `goods:purchase:self` |
 | `useTip()` | `tip()` | `social:tip:self` |
 

package/dist/hooks/useBuzzPurchase.d.ts

@@ -9,7 +9,9 @@ export interface UseBuzzPurchase {
  * Opens the Civitai Buzz purchase modal on the host. Resolves with the
  * outcome when the user closes the modal — `purchased: true` means the
  * balance increased; the new balance is included if the host reports it.
- * The insufficient-budget recovery path for {@link useBuzzWorkflow}.
+ * Raises the viewer's WALLET, never a spend cap: offer it when the viewer's
+ * spendable Buzz is below a quoted cost, never on a resolved `failed` submit
+ * from {@link useBuzzWorkflow} (see its `submit` docs for why).
  *
  * 🔴 HUMAN-GATED: the reply comes when the viewer closes the modal, and a
  * payment flow is nowhere near a ~30s round-trip — so this passes

package/dist/hooks/useBuzzPurchase.js

@@ -6,7 +6,9 @@ import { sendTypedRequest } from '../transport/transport.js';
  * Opens the Civitai Buzz purchase modal on the host. Resolves with the
  * outcome when the user closes the modal — `purchased: true` means the
  * balance increased; the new balance is included if the host reports it.
- * The insufficient-budget recovery path for {@link useBuzzWorkflow}.
+ * Raises the viewer's WALLET, never a spend cap: offer it when the viewer's
+ * spendable Buzz is below a quoted cost, never on a resolved `failed` submit
+ * from {@link useBuzzWorkflow} (see its `submit` docs for why).
  *
  * 🔴 HUMAN-GATED: the reply comes when the viewer closes the modal, and a
  * payment flow is nowhere near a ~30s round-trip — so this passes

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,5 +1,18 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
 import type { ConsentRetryOptions } from './consentRetryOptions.js';
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a `kind: 'training'` body.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, NOT LEFT TO THE SERVER. The server charges a
+ * training run only against a quote the viewer confirmed from a signed-in
+ * session, and only `RUN_TRAINING`'s host-chrome dialog can record that — so a
+ * `SUBMIT_WORKFLOW` carrying this body can never start a run. Refusing here
+ * turns a server round-trip ending in a confusing refusal into an immediate
+ * error that names the hook to use. Nothing is sent and nothing is spent, which
+ * is why it is a plain `Error` and not a {@link WorkflowSubmitError} (every code
+ * on that class is money-ambiguous by design).
+ */
+export declare const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body \u2014 estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -258,10 +271,11 @@ export type WorkflowSubmitErrorCode = 'exception' | 'workflow-failed';
  *
  *   - **budget / spend-cap REJECTION** — a legitimate OUTCOME. The server quotes
  *     the price it refused to charge, so the snapshot carries a numeric
- *     `cost.total`. Blocks recover from it (open a top-up flow), so it MUST keep
- *     RESOLVING. Every such exit on the server attaches a cost: the per-call
- *     `buzzBudget` gate, the per-user daily Buzz cap, the per-app aggregate and
- *     velocity caps, and the dev-tunnel session cap — on all three body kinds.
+ *     `cost.total`, and the block can tell the viewer what was refused and why,
+ *     so it MUST keep RESOLVING. It is NOT a top-up cue: these are app and
+ *     platform caps, and buying Buzz raises none of them. Every such exit on
+ *     the server attaches a cost; the complete list of them, and of the other
+ *     resolved `'failed'` replies, is on {@link UseBuzzWorkflow.submit}.
  *   - **caught server EXCEPTION** — `failureSnapshot(err)`, no `cost`, and the
  *     `'failed'` sentinel id. The host had no workflow to report — usually
  *     nothing was queued, but a lost response or an in-progress idempotency
@@ -309,8 +323,8 @@ export type WorkflowSubmitErrorCode = 'exception' | 'workflow-failed';
  *
  * 🔴 DO NOT "SIMPLIFY" THIS BY PUTTING `snapshot.error` BACK ON `message`, and do
  * not widen the guard to reject a budget rejection. The first re-opens #253; the
- * second breaks the top-up recovery flow, which is the one thing #251 says must
- * not break.
+ * second turns a priced, explainable refusal into an opaque exception, which is
+ * the one thing #251 says must not happen.
  */
 export declare class WorkflowSubmitError extends Error {
     /**
@@ -465,6 +479,10 @@ export interface UseBuzzWorkflow {
      * consent dialog with no user gesture behind it, once per edit. A missing
      * scope surfaces as an ordinary rejection; show no price and let `submit()`
      * do the asking.
+     *
+     * A `kind: 'training'` body's reply also carries
+     * {@link BlockWorkflowSnapshot.trainingQuote} — the `quoteId` to run it with
+     * through `useRunTraining()`.
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -486,14 +504,67 @@ export interface UseBuzzWorkflow {
      * 🔴 A BUDGET / SPEND-CAP REJECTION STILL RESOLVES, and that is deliberate. It
      * is a documented outcome, not an error: the server quotes what it refused to
      * charge, so the resolved snapshot has `status === 'failed'` AND a numeric
-     * `cost.total`. THAT is the shape to branch on when offering a top-up —
-     * `useBuzzPurchase().openPurchaseModal()` — not a `catch`.
-     *
-     * 🔴 BUT A RESOLVED `'failed'` IS NOT ALWAYS AN AFFORDABILITY PROBLEM, so do not
-     * wire every one of them to a purchase modal. The per-app **velocity** limit,
-     * the per-app **aggregate daily** cap, a fail-closed "temporarily unavailable"
-     * deny and a **missing price quote** are all priced, resolving outcomes that
-     * buying Buzz cannot fix.
+     * `cost.total`.
+     *
+     * 🔴 WHAT A RESOLVED `status: 'failed'` CAN MEAN — THE ONE COMPLETE LIST. The
+     * `@civitai/blocks-react` README, the `civitai-block-starter` AGENTS.md and the
+     * changesets link here rather than restating it. Every case below RESOLVES
+     * (`blocks.submitWorkflow` returns it; the REST route answers it with HTTP
+     * 200):
+     *
+     * 1. **Refused before anything ran — the `'failed'` sentinel `workflowId`, a
+     *    `cost.total`, nothing charged, every reservation released.**
+     *    - the per-call budget, `token.buzzBudget` (`insufficient buzz budget: …`);
+     *    - the viewer's daily Buzz cap — or, in its place, the review-session cap
+     *      (a moderator's run-for-real) or the private-run cap;
+     *    - the viewer's consent budget (the ceiling they set when they granted the
+     *      scope);
+     *    - the app's velocity limit or aggregate daily cap, or a fail-closed
+     *      "temporarily unavailable" deny;
+     *    - the dev-session cap (`dev:tunnel`);
+     *    - a missing price quote for a step ("generation temporarily unavailable").
+     *
+     *    A training step with no price quote is refused the same way but with NO
+     *    `cost`, which on this hook REJECTS as `'exception'` instead.
+     * 2. **Not confirmed — Buzz may have been spent.** A training run whose
+     *    submission the server could not confirm: the sentinel id, a `cost.total`,
+     *    and `submissionUnconfirmed: true` on the REST reply. The reservation is NOT
+     *    refunded and the run may be going. 🔴 The host bridge forwards only the
+     *    snapshot, so on this hook that flag never arrives and the reply looks like
+     *    case 1 — never tell a viewer "nothing was charged" for a resolved failed
+     *    `kind: 'training'` submit; send them to their trainings instead.
+     * 3. **A run was created and came back failed — a REAL `workflowId`.** The
+     *    reservation is kept and Buzz may have been spent. Priced, it resolves;
+     *    unpriced, it rejects as `'workflow-failed'`.
+     *
+     * So only case 1 may be told "could not start, nothing was charged".
+     *
+     * 🔴 A RESOLVED `'failed'` IS NEVER A TOP-UP CUE — do not wire it to
+     * `useBuzzPurchase().openPurchaseModal()`. Case 1 is a set of caps that buying
+     * Buzz does not raise, and cases 2 and 3 are not about the wallet.
+     *
+     * 🔴 THE CASE A TOP-UP DOES FIX — THE VIEWER IS ACTUALLY OUT OF BUZZ — REJECTS.
+     * The orchestrator refuses the run, the server throws, and the host answers
+     * with its cost-less `failureSnapshot(err)`, so this rejects with
+     * {@link WorkflowSubmitError} code **`'exception'`** — the same code as every
+     * other thrown submit (a bad request, an outage, a rate limit, an idempotency
+     * conflict). Nothing structural marks it as insufficient funds: the code is
+     * shared, and `snapshot.error` is the upstream message, server-authored prose
+     * that is not a contract. So decide a top-up from the BALANCE, not from the
+     * rejection: on `'exception'`, read {@link useBuzzBalance} and offer
+     * `openPurchaseModal()` only if the viewer's SPENDABLE Buzz is below the quoted
+     * cost. Two things make that read correct:
+     * - `useBuzzBalance` needs `buzz:read:self` declared in `block.manifest.json`,
+     *   and that scope is consent-gated (it is not consent-exempt), so request it
+     *   like any other gated scope. An anonymous viewer is refused outright.
+     * - A block spends only blue plus ITS DOMAIN'S pool: blue + green under an SFW
+     *   ceiling, blue + yellow under a mature one. The server keys this on the
+     *   token's DOMAIN ceiling (`maxBrowsingLevel`), so compute it as
+     *   `isSfwCeiling(useDomainMaturity().maxBrowsingLevel)` (from
+     *   `@civitai/app-sdk/blocks`; an unknown ceiling counts as SFW) — NOT
+     *   `useDomainMaturity().isSfw`, which is narrowed by the viewer's own setting —
+     *   and compare `blue` plus that one pool, never blue + green + yellow, against
+     *   the quoted cost.
      *
      * 🔴 THIS ALSO INCLUDES MODERATOR REVIEW PREVIEW. While an app is under review
      * the host short-circuits every workflow request with
@@ -512,6 +583,9 @@ export interface UseBuzzWorkflow {
      * `CONSENT_UNAVAILABLE` environment is never retried, and a second consent
      * failure reaches you unchanged. Opt out with
      * {@link ConsentRetryOptions.autoRequestConsent}`: false`.
+     *
+     * 🔴 A `kind: 'training'` BODY IS REFUSED before anything is sent — it runs
+     * only through `useRunTraining()`. See {@link TRAINING_BODY_SUBMIT_REFUSAL}.
      */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -566,15 +640,18 @@ export interface UseBuzzWorkflow {
  *
  * 🔴 A BUDGET REFUSAL DOES **NOT** REJECT — IT RESOLVES. It comes back as a
  * snapshot with `status: 'failed'`, an `error` string and the `cost` the server
- * declined to charge, and THAT resolved shape is the cue to call
- * `useBuzzPurchase().openPurchaseModal()`. What DOES reject is a submit with no
- * usable outcome — see {@link WorkflowSubmitError}. Routing a rejection into a
- * top-up sells Buzz for a failure Buzz cannot fix.
+ * declined to charge. It is NOT a cue to call
+ * `useBuzzPurchase().openPurchaseModal()`: every resolving refusal is a cap
+ * buying Buzz does not raise, or a reply that is not about the wallet at all —
+ * the complete list is on {@link UseBuzzWorkflow.submit}.
  *
- * 🔴 NOR IS EVERY RESOLVED `'failed'` AN AFFORDABILITY PROBLEM. The per-app
- * velocity limit, the per-app aggregate daily cap, a fail-closed "temporarily
- * unavailable" deny and a missing price quote are all priced, resolving outcomes
- * too. Branch on the message/your own policy before offering to sell anything.
+ * 🔴 RUNNING OUT OF BUZZ REJECTS, and is not marked as such. The orchestrator's
+ * refusal reaches the block as {@link WorkflowSubmitError} code `'exception'`,
+ * shared with every other thrown submit. Offer a top-up only after checking the
+ * viewer's SPENDABLE Buzz ({@link useBuzzBalance}: blue plus the block's domain
+ * pool, `buzz:read:self` declared) against the quoted cost — see
+ * {@link UseBuzzWorkflow.submit}, which also holds the complete list of resolved
+ * refusals.
  *
  * AFTER `submit` FLIPS `status` TO `'polling'`, USE `watch(workflowId)`. It owns
  * the loop, resolves on the terminal snapshot, and pushes every intermediate
@@ -652,8 +729,9 @@ export interface UseBuzzWorkflow {
  * try {
  *   const snap = await submit(body); // status 'submitting' → 'polling'
  *   if (snap.status === 'failed') {
- *     // RESOLVED + priced = a server outcome (affordability, a cap, a velocity
- *     // limit, a transient deny). Only some of those are fixable by buying Buzz.
+ *     // RESOLVED = a server outcome: a cap, a limit, a missing quote — none of
+ *     // them fixed by buying Buzz — or a run that may have spent (see `submit`
+ *     // for the complete list). Never a top-up cue.
  *     showError(submitOutcomeMessage(snap));
  *   } else {
  *     const done = await watch(snap.workflowId, { onUpdate: render }); // → terminal

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
 import { withConsentRetry } from '../internal/withConsentRetry.js';
+import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
 /**
@@ -16,6 +17,19 @@ import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.
  * automatic prompt silently do nothing.
  */
 const WORKFLOW_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a `kind: 'training'` body.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, NOT LEFT TO THE SERVER. The server charges a
+ * training run only against a quote the viewer confirmed from a signed-in
+ * session, and only `RUN_TRAINING`'s host-chrome dialog can record that — so a
+ * `SUBMIT_WORKFLOW` carrying this body can never start a run. Refusing here
+ * turns a server round-trip ending in a confusing refusal into an immediate
+ * error that names the hook to use. Nothing is sent and nothing is spent, which
+ * is why it is a plain `Error` and not a {@link WorkflowSubmitError} (every code
+ * on that class is money-ambiguous by design).
+ */
+export const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body — estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -27,18 +41,16 @@ const TERMINAL_STATUSES = new Set([
     'canceled',
     'expired',
 ]);
-/**
- * The workflow requests (estimate / submit / poll) are orchestrator-bound:
- * the host forwards them to the generation orchestrator and only replies
- * once it answers. `submit` is the slowest — server-side it does a whatif
- * cost-preflight AND the real submit (two orchestrator round-trips) plus a
- * prompt audit before responding, which legitimately exceeds the
- * transport's 30s `DEFAULT_REQUEST_TIMEOUT_MS` (tuned for fast bridge
- * messages) when the orchestrator queue is busy. Give these calls a
- * generous ceiling so a busy-but-healthy orchestrator doesn't surface as
- * a spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
- */
-const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
+// The workflow requests (estimate / submit / poll) are orchestrator-bound:
+// the host forwards them to the generation orchestrator and only replies
+// once it answers. `submit` is the slowest — server-side it does a whatif
+// cost-preflight AND the real submit (two orchestrator round-trips) plus a
+// prompt audit before responding, which legitimately exceeds the
+// transport's 30s `DEFAULT_REQUEST_TIMEOUT_MS` (tuned for fast bridge
+// messages) when the orchestrator queue is busy. `WORKFLOW_REQUEST_TIMEOUT_MS`
+// (imported above, from `transport/requestTimeouts.ts`) gives these calls a
+// generous ceiling so a busy-but-healthy orchestrator doesn't surface as a
+// spurious `request "SUBMIT_WORKFLOW" timed out` rejection.
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -288,10 +300,11 @@ const HOST_SYNTHESISED_WORKFLOW_ID = 'failed';
  *
  *   - **budget / spend-cap REJECTION** — a legitimate OUTCOME. The server quotes
  *     the price it refused to charge, so the snapshot carries a numeric
- *     `cost.total`. Blocks recover from it (open a top-up flow), so it MUST keep
- *     RESOLVING. Every such exit on the server attaches a cost: the per-call
- *     `buzzBudget` gate, the per-user daily Buzz cap, the per-app aggregate and
- *     velocity caps, and the dev-tunnel session cap — on all three body kinds.
+ *     `cost.total`, and the block can tell the viewer what was refused and why,
+ *     so it MUST keep RESOLVING. It is NOT a top-up cue: these are app and
+ *     platform caps, and buying Buzz raises none of them. Every such exit on
+ *     the server attaches a cost; the complete list of them, and of the other
+ *     resolved `'failed'` replies, is on {@link UseBuzzWorkflow.submit}.
  *   - **caught server EXCEPTION** — `failureSnapshot(err)`, no `cost`, and the
  *     `'failed'` sentinel id. The host had no workflow to report — usually
  *     nothing was queued, but a lost response or an in-progress idempotency
@@ -339,8 +352,8 @@ const HOST_SYNTHESISED_WORKFLOW_ID = 'failed';
  *
  * 🔴 DO NOT "SIMPLIFY" THIS BY PUTTING `snapshot.error` BACK ON `message`, and do
  * not widen the guard to reject a budget rejection. The first re-opens #253; the
- * second breaks the top-up recovery flow, which is the one thing #251 says must
- * not break.
+ * second turns a priced, explainable refusal into an opaque exception, which is
+ * the one thing #251 says must not happen.
  */
 export class WorkflowSubmitError extends Error {
     /**
@@ -452,15 +465,18 @@ export class WorkflowSubmitError extends Error {
  *
  * 🔴 A BUDGET REFUSAL DOES **NOT** REJECT — IT RESOLVES. It comes back as a
  * snapshot with `status: 'failed'`, an `error` string and the `cost` the server
- * declined to charge, and THAT resolved shape is the cue to call
- * `useBuzzPurchase().openPurchaseModal()`. What DOES reject is a submit with no
- * usable outcome — see {@link WorkflowSubmitError}. Routing a rejection into a
- * top-up sells Buzz for a failure Buzz cannot fix.
- *
- * 🔴 NOR IS EVERY RESOLVED `'failed'` AN AFFORDABILITY PROBLEM. The per-app
- * velocity limit, the per-app aggregate daily cap, a fail-closed "temporarily
- * unavailable" deny and a missing price quote are all priced, resolving outcomes
- * too. Branch on the message/your own policy before offering to sell anything.
+ * declined to charge. It is NOT a cue to call
+ * `useBuzzPurchase().openPurchaseModal()`: every resolving refusal is a cap
+ * buying Buzz does not raise, or a reply that is not about the wallet at all —
+ * the complete list is on {@link UseBuzzWorkflow.submit}.
+ *
+ * 🔴 RUNNING OUT OF BUZZ REJECTS, and is not marked as such. The orchestrator's
+ * refusal reaches the block as {@link WorkflowSubmitError} code `'exception'`,
+ * shared with every other thrown submit. Offer a top-up only after checking the
+ * viewer's SPENDABLE Buzz ({@link useBuzzBalance}: blue plus the block's domain
+ * pool, `buzz:read:self` declared) against the quoted cost — see
+ * {@link UseBuzzWorkflow.submit}, which also holds the complete list of resolved
+ * refusals.
  *
  * AFTER `submit` FLIPS `status` TO `'polling'`, USE `watch(workflowId)`. It owns
  * the loop, resolves on the terminal snapshot, and pushes every intermediate
@@ -538,8 +554,9 @@ export class WorkflowSubmitError extends Error {
  * try {
  *   const snap = await submit(body); // status 'submitting' → 'polling'
  *   if (snap.status === 'failed') {
- *     // RESOLVED + priced = a server outcome (affordability, a cap, a velocity
- *     // limit, a transient deny). Only some of those are fixable by buying Buzz.
+ *     // RESOLVED = a server outcome: a cap, a limit, a missing quote — none of
+ *     // them fixed by buying Buzz — or a run that may have spent (see `submit`
+ *     // for the complete list). Never a top-up cue.
  *     showError(submitOutcomeMessage(snap));
  *   } else {
  *     const done = await watch(snap.workflowId, { onUpdate: render }); // → terminal
@@ -687,10 +704,11 @@ export function useBuzzWorkflow() {
         // `submit` half of civitai/civitai#4159). Two producers report
         // `status:'failed'` and `status` separates neither:
         //
-        //   - a budget / spend-cap REJECTION is an OUTCOME the block recovers from
-        //     (open a top-up flow). The server quotes the price it refused to
-        //     charge, so `cost.total` is present. It RESOLVES — turning this arm
-        //     into a throw is the one change that would break the recovery path.
+        //   - a budget / spend-cap REJECTION is an OUTCOME the block reports (the
+        //     run did not start, at this quoted price). The server quotes the price
+        //     it refused to charge, so `cost.total` is present. It RESOLVES —
+        //     turning this arm into a throw would erase that. (It is not a top-up
+        //     cue: buying Buzz raises none of these caps.)
         //   - a failure-shaped reply with NO `cost` is not a usable outcome. It
         //     REJECTS — and the `code` says which kind, because they differ on
         //     whether money moved (see WorkflowSubmitError.code).
@@ -720,6 +738,14 @@ export function useBuzzWorkflow() {
         return snapshot;
     }, []);
     const submit = useCallback(async (body, options) => {
+        // See `TRAINING_BODY_SUBMIT_REFUSAL`. Before the status flip, the key
+        // mint and the consent retry: nothing about this call may reach the wire.
+        if (body.kind === 'training') {
+            const refused = new Error(TRAINING_BODY_SUBMIT_REFUSAL);
+            setError(refused);
+            setStatus('error');
+            throw refused;
+        }
         setError(null);
         setStatus('submitting');
         // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz

package/dist/hooks/useGoodPurchase.d.ts

@@ -52,13 +52,13 @@ export interface GoodPurchaseOptions extends ConsentRetryOptions {
      * fresh key here would work too, but it would make a lost response on the
      * retry unrecoverable, which is the thing idempotency keys exist to prevent.
      *
-     * ⚠️ RECONCILED WITH THE OPPOSITE POLICY NEXT DOOR, which a reader will hit.
-     * `useBuzzWorkflow` states twice that a resolved-failed budget "is the cue to
-     * call `useBuzzPurchase().openPurchaseModal()`" — i.e. the APP decides — and
-     * warns that "routing a rejection into a top-up sells Buzz for a failure Buzz
-     * cannot fix". That policy is right for a generation, and this option does not
-     * contradict it: it defaults to `false`, and it keys on the REASON
-     * (`insufficient_funds`) rather than on "the call failed", so it never offers
+     * ⚠️ RECONCILED WITH THE POLICY NEXT DOOR, which a reader will hit.
+     * `useBuzzWorkflow` says a resolved-failed generation is never a top-up cue
+     * (those are caps Buzz does not raise) and that running out of Buzz there
+     * rejects without a structural marker, so the APP decides a top-up from the
+     * balance. This option does not contradict that: it defaults to `false`, and
+     * it keys on the REASON (`insufficient_funds`, which a goods purchase DOES
+     * report structurally) rather than on "the call failed", so it never offers
      * Buzz for a failure Buzz cannot fix. What it buys, and the only reason it is
      * in the library at all rather than left to each app, is the same-key retry
      * above — a server contract an app gets wrong in the expensive direction.