@civitai/app-sdk 0.48.0 → 0.50.0

package/README.md

@@ -23,9 +23,31 @@ pnpm add @civitai/app-sdk
 | `manifest/*` — `defineBlock`, `SCHEMA_DIVERGENCES`, `KNOWN_GAPS` (**Node only**) | Build-time manifest validation. `defineBlock(config)` compiles the vendored canonical schema with [Ajv](https://ajv.js.org) and validates a `BlockManifestV1` against it, so authoring mistakes surface in `pnpm dev` instead of at `civitai app validate`/submit. It is **derived from the schema, not a hand-written mirror of it** — that mirror is what produced [#330](https://github.com/civitai/civitai-app-starters/issues/330). Needs `node:fs` and the optional peer `ajv`, which is why it is not on the browser-facing `./blocks` surface. |
 | `vite/*` — `blockManifestPlugin` (**Node only**) | A Vite plugin wrapping `defineBlock`, firing from `configResolved` — the one hook Vite calls on both the dev-server and the build path. Every block scaffold registers it, so `pnpm dev`, `pnpm dev:harness` and `pnpm build` all fail on a bad manifest with the offending field path. Optional peers: `ajv` (runtime) and `vite` (types only). |
 
+## Entry points, and what the root barrel is
+
+The root — `import … from '@civitai/app-sdk'` — is **exactly the union of four subpaths**: `@civitai/app-sdk/oauth`, `/scopes`, `/cookies` and `/orchestrator`. All of each, and nothing else. Import from the root when you want the OAuth-app surface in one specifier; import a subpath when you want only that slice. The two are the same symbols either way, which is asserted in both directions by `test/export-surface.test.ts` — the root cannot quietly gain a symbol none of those four exports, or miss one they do.
+
+The other five subpaths are **deliberately not on the root**, each for a concrete cost it would push onto every consumer:
+
+| Subpath | Why it is not on the root |
+|---|---|
+| `@civitai/app-sdk/blocks` | Importing it runs `/safe-storage` for its side effect, and it is the Civitai-Apps contract — a disjoint audience from OAuth apps. |
+| `@civitai/app-sdk/safe-storage` | Its purpose *is* the module side effect. A side effect on the root barrel is not something a consumer can opt out of. |
+| `@civitai/app-sdk/orchestrator/steps` | Type-only, and its declarations name `@civitai/client` — an **optional** peer that the root would make mandatory for everyone. |
+| `@civitai/app-sdk/manifest` | **Node only** — needs `node:fs` and the optional peer `ajv`. |
+| `@civitai/app-sdk/vite` | **Node only** — optional peers `ajv` (runtime) and `vite` (types). |
+
+> One name is declared twice on purpose: `BuzzAccountType` is the full set of Civitai Buzz pools on the root and `/oauth`, and a narrower three-pool union on `/blocks` — a block can neither prefer nor read the others. Same name, two subpaths, two types; the divergence is pinned rather than merged.
+
 ## Subpath imports
 
 ```ts
+// The OAuth-app surface, also available whole from the root specifier:
+import { buildAuthorizeUrl, exchangeCode, type OAuthTokens } from '@civitai/app-sdk/oauth';
+import { TokenScope, bitmaskFromScopes } from '@civitai/app-sdk/scopes';
+import { sealCookie, unsealCookie } from '@civitai/app-sdk/cookies';
+import { submitWorkflow, WORKFLOW_STEP_TYPES } from '@civitai/app-sdk/orchestrator';
+// The Civitai Apps contract (a different audience — see above):
 import { BLOCK_SCOPES, isSignedIn } from '@civitai/app-sdk/blocks';
 // Build-time manifest validation (NODE ONLY — needs the optional peer `ajv`).
 // Most projects want the Vite plugin below rather than calling this directly:
@@ -420,7 +442,7 @@ The starters in `civitai/civitai-app-starters` wire this into framework-specific
 
 ## Choosing a workflow step type
 
-The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler`, and 38 more (47 in total).
+The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (50 in total).
 
 The catalog is pinned to the orchestrator's published OpenAPI spec two ways — an offline unit test against a transcribed copy of the spec's `WorkflowStepTemplate` discriminator mapping, and a CI job (`pnpm check:catalogs`) that re-fetches the live spec and diffs it. If a `$type` is listed here, the orchestrator accepts it.
 
@@ -495,12 +517,16 @@ What it exports:
 
 | Export | What |
 |---|---|
-| `WorkflowStepTemplates` | `$type` → template type, for all 47 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
+| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 50 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
 | `WorkflowStepTemplateFor<'videoGen'>` | One step's template. |
 | `WorkflowStepInputFor<'videoGen'>` | One step's `input` shape, without needing the generated `*Input` name. |
-| `AnyWorkflowStepTemplate` | Discriminated union of all 47 — `Extract<…, { $type: 'comfy' }>` and exhaustive `switch` work. `@civitai/client`'s base `WorkflowStepTemplate` has `$type` as a bare `string`, so it narrows nothing. |
+| `AnyWorkflowStepTemplate` | Discriminated union of all 47 mapped templates — `Extract<…, { $type: 'comfy' }>` and exhaustive `switch` work. `@civitai/client`'s base `WorkflowStepTemplate` has `$type` as a bare `string`, so it narrows nothing. |
 | `TypedWorkflowTemplate` | The submit envelope with `steps` narrowed to that union. Pass it straight to `submitWorkflow` / `estimateWorkflow`. |
 
+> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with no generated template in the pinned `@civitai/client` are `imageScanning`, `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
+>
+> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (50, 47, 3, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
+
 The generated `*StepTemplate` and `*Input` types are **not** re-exported individually. Using this subpath already requires `@civitai/client` installed, so if you want one by name, import it straight from there — `import type { TextToImageStepTemplate } from '@civitai/client'`.
 
 In practice `WorkflowStepTemplateFor<T>` and `WorkflowStepInputFor<T>` are the better route: they take the wire `$type` you already have, rather than the generated name you would otherwise have to go look up (`model3DPreview` → `Model3dPreviewStepTemplate`).
@@ -536,7 +562,7 @@ A `$type` having a type here says nothing about whether you may submit it.
 
 Several of the 47 exist to serve Civitai's own pipelines rather than third-party apps — `modelPickleScan`, `xGuardModeration`, `training`, `comfyNodepackSnapshot`, `qwenImageBench`, the `model*`/`media*` hashing and classification steps. They're in the consumer spec, so they're typed here. They are not an invitation.
 
-Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 47 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason all 47 are typed is not that the catalog flags the internals; it's that the catalog *documents* all 47 and a `$type`-keyed lookup is only sound as a lookup if it's total — a partial map would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents, and would make the key-parity assertion impossible.
+Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 50 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
 
 ## Public vs. confidential clients
 

package/dist/blocks/appStorageErrors.d.ts

@@ -0,0 +1,390 @@
+/**
+ * The App Storage rejection MESSAGES the host puts on the wire — the only site
+ * in this repository that spells them **in executable code**, sibling of
+ * `appStorageLimits.ts`, which owns the numbers.
+ *
+ * 🔴 **"IN EXECUTABLE CODE" IS THE WHOLE CLAIM — do not read it wider.** What
+ * `tests/guards/app-storage-error-strings.test.mjs` actually enforces is
+ * narrower still: every `error:` value inside an `APP_STORAGE_*_RESULT` payload
+ * in the scanned mocks must NAME a constant from this module. It sees nothing
+ * else. Hand-typed copies of these six strings live today in
+ * `mockHost.ts`'s option docblocks (which ship in the published `.d.ts`),
+ * in `blocks-react/test/validate.test.ts`'s fixture, in this guard's own
+ * control assertions, and in both READMEs — and every one of them is invisible
+ * to the guard. If the host rewords a message they go stale silently. Grep the
+ * literal, not just the identifier, when a message moves.
+ *
+ * 🔴 **THE WIRE CARRIES A MESSAGE, NOT A CODE.** The host's router throws a
+ * `TRPCError` that has BOTH: `code: 'PAYLOAD_TOO_LARGE'` and a per-site
+ * `message`. The bridge that answers `APP_STORAGE_SET` forwards
+ * **`err.message`** and never the code, so `PAYLOAD_TOO_LARGE` is a string a
+ * block CANNOT receive. `createMockHost` emitted it anyway for three releases:
+ * a block that branched on it took the actionable branch under `dev:mock` and
+ * the generic one in production, and nothing local could see the difference.
+ * That is civitai/civitai-app-starters#343, and this module is its fix — one
+ * spelling, shared by the mock, the example harness and any block matcher.
+ *
+ * ## 🔴 There is NO list here of "every string a block can receive" — on purpose
+ *
+ * **This is the THIRD attempt at this section, and the absence of that list is
+ * what the first two attempts cost. It is not an omission to be helpfully
+ * filled in.** Both earlier drafts shipped, and each was wrong by more than its
+ * author had checked:
+ *
+ *   1. **Draft 1 (RETRACTED)** presented six strings as "every storage-rejection
+ *      string the host can put on the wire". It had read only the
+ *      `PAYLOAD_TOO_LARGE` sites, so it missed the entire authorization family.
+ *   2. **Draft 2 (RETRACTED)** kept the six, added a table of eight
+ *      authorization messages "measured in the same read", and presented THAT
+ *      as the surface. Also wrong. It missed, in the same file: `Apps are not
+ *      enabled`, thrown from TWO different gates with one spelling — the
+ *      `enforceAppBlocksFlag` middleware (defined `:249`, throws at `:255`
+ *      query / `:257` mutation), which is `.use()`d on all five storage
+ *      procedures at `:470`, `:509`, `:938`, `:1022`, `:1106` BEFORE their
+ *      `.input()`, so it fires before anything else on every call; and
+ *      `assertAppBlocksEnabledForTokenUser` (`:139-155`, throwing at `:153`),
+ *      reached from `resolveStorageContext`. Grepping `enforceAppBlocksFlag`
+ *      will NOT find `:153`. Also missed: `block token subject could
+ *      not be resolved` (`:148`, called unconditionally from
+ *      `resolveStorageContext`), `review token subject could not be resolved`
+ *      (`:82`) and `Apps authoring is not enabled for this account` (`:89`).
+ *      `Apps are not enabled` is a feature-flag kill switch — neither a ceiling
+ *      nor an authorization failure, so it fit neither published table.
+ *
+ * Each enumeration was wider than the last and each was still short; the
+ * router carries **21** `throw new TRPCError` sites and **17** distinct
+ * messages, against draft 2's 14. A third list would be the same defect a third
+ * time.
+ *
+ * 🔴 **The completeness claim is the wrong SHAPE, not merely a stale list.** The
+ * failure is not "this might go out of date" — it is that "the set of strings a
+ * block can receive" is the host's whole error surface, which this repository
+ * does not own, cannot observe from here, and has now mis-measured twice while
+ * believing otherwise. Do not soften this into "the list below may be
+ * incomplete" and restore one. What replaces it needs no completeness at all:
+ *
+ * - **This module classifies the `PAYLOAD_TOO_LARGE` family plus the bridge's
+ *   fallback — a set THIS REPOSITORY CHOSE, not a set the host guarantees
+ *   closed.** It is the five `PAYLOAD_TOO_LARGE` throws in `apps.router.ts`
+ *   (`:568`, `:783`, `:791`, `:845`, `:853`) and the `'storage request failed'`
+ *   literal at `IframeHost.tsx:287`. Naming what it classifies is a decision
+ *   about scope; it needs no completeness claim to be useful, and it must not
+ *   be dressed as one. 🔴 **A ceiling the host enforces OUTSIDE that family
+ *   already exists** — see "Ceilings outside this set" below.
+ * - **Every OTHER host rejection reaches a block on the same `error` field and
+ *   classifies `null`.** This is the whole of what a block author needs, it
+ *   requires no enumeration, and it stays true when the host adds, rewords or
+ *   deletes a message. It holds STRUCTURALLY, from two facts rather than from a
+ *   survey: the bridge's catch arms are **blanket** `catch (err)` with no code
+ *   filter (`IframeHost.tsx:2395` GET, `:2427` SET, `:2458` DELETE, `:2508`
+ *   LIST, `:2535` QUOTA), each forwarding `err.message` verbatim via
+ *   `storageErrorMessage()`; and {@link classifyAppStorageError} answers `null`
+ *   for everything outside the ceiling patterns, which is checkable in this
+ *   file without consulting the host at all.
+ * - **The RECIPE beats any prose in this repository — and is still NOT a
+ *   completeness check.** It is strictly wider than every list anyone has
+ *   written: it found all 21 `TRPCError` sites, including the four draft 2
+ *   missed. It is NECESSARY, NOT SUFFICIENT — see "What the recipe cannot
+ *   see" under "Re-deriving it".
+ *
+ * ## Ceilings outside this set
+ *
+ * 🔴 **The host enforces size ceilings that are NOT `TRPCError` throws and are
+ * therefore invisible to both the recipe and this module.** They are zod
+ * `.max()` bounds on the procedures' `.input()` schemas, so tRPC refuses the
+ * call with `BAD_REQUEST` before any handler runs. Measured in
+ * `apps.router.ts` on `civitai/civitai` `main`, 2026-09-21:
+ *
+ *   - `const keyInput = z.string().min(1).max(200)` (`:460`) — the `key`
+ *     argument of `get` (`:471`), `set` (`:511`) and `delete` (`:939`);
+ *   - `list` (`:1025-1027`): `prefix: z.string().max(200)`,
+ *     `cursor: z.string().max(400)`, `limit: …int().min(1).max(200)`.
+ *
+ * 🔴 **The 200-character KEY cap is the one a real block hits with no local
+ * warning.** Derive a key from a URL, a model name or a title and 201
+ * characters is ordinary. Nothing in this repository caps it: `useAppStorage`
+ * and `createMockHost` forward the key verbatim and the mock enforces no length
+ * gate (civitai/civitai-app-starters#370), so the write succeeds under
+ * `dev:mock` and fails forever in production. The zod refusal arrives on the
+ * same `error` field as everything else, so {@link classifyAppStorageError}
+ * answers `null` — and the recommended `null` copy ("try reloading the page")
+ * is WRONG for it: reloading re-mints the token and the write fails
+ * identically. If a block builds keys from untrusted-length input, cap or hash
+ * them at the block, and do not rely on a local run to tell you.
+ *
+ * 🔴 **So: wherever a list of host strings still appears — in this repo's
+ * READMEs, in the changeset, in `messages.ts`, in `@civitai/blocks-react`'s
+ * `src/hooks/useAppStorage.ts`, in the `kv-storage` example's `src/App.tsx`
+ * (which is where the "try reloading" copy lives), or in
+ * `test/blocks/appStorageErrors.test.ts` — it is ILLUSTRATIVE, NOT EXHAUSTIVE,
+ * and must be labelled as such.** Its job is to show a reader what the `null`
+ * bucket typically contains, never to bound it.
+ *
+ * ## Re-deriving it
+ *
+ * 🔴 **Not a `PAYLOAD_TOO_LARGE`-only grep** — that is structurally incapable of
+ * seeing anything but the ceiling family, and is how draft 1 came to claim a
+ * completeness it had not measured.
+ *
+ * ```sh
+ * # EVERY throw, not one code. Read the whole output; do not count from memory.
+ * gh api repos/civitai/civitai/contents/src/server/routers/apps.router.ts \
+ *   --jq '.content' | base64 -d | grep -n "new TRPCError" -A4
+ * # …and confirm the catch arms are still blanket (no code filter), which is
+ * # what makes "everything else classifies null" true:
+ * gh api repos/civitai/civitai/contents/src/components/AppBlocks/IframeHost.tsx \
+ *   --jq '.content' | base64 -d | grep -n "storageErrorMessage" -B12
+ * # …and the zod caps, which throw no TRPCError and so appear in NEITHER of the
+ * # two commands above:
+ * gh api repos/civitai/civitai/contents/src/server/routers/apps.router.ts \
+ *   --jq '.content' | base64 -d | grep -n "z\.string()\|z\.number()\|\.max("
+ * ```
+ *
+ * ### What the recipe cannot see
+ *
+ * 🔴 **A clean run of the three commands above is NOT proof of completeness —
+ * do not treat it as one.** Measured blind spots, both of which bit this file:
+ *
+ *   - **zod-enforced caps.** They are `.input()` bounds, not throws, so
+ *     `grep "new TRPCError"` cannot see them at all. That is why the third
+ *     command exists — and why "a new ceiling can only arrive as a new
+ *     `PAYLOAD_TOO_LARGE` throw" was deleted from this header: it was false
+ *     when it was written. See "Ceilings outside this set" above.
+ *   - **the bridge's own literal.** `'storage request failed'` is at
+ *     `IframeHost.tsx:287`, and `grep … -B12` prints the twelve lines BEFORE
+ *     each match — for the definition at `:282` that is 270–282, so line 287
+ *     never appears in the output. The recipe enumerates the CALL SITES of
+ *     `storageErrorMessage`, not its fallback. Read the function body.
+ *
+ * 🔴 **DO NOT re-derive the ceiling strings from this comment** — re-read the
+ * host. These are prose a server engineer wrote, not a published contract: they
+ * can be reworded in any deploy, and nothing will tell you. Which is also why
+ * {@link classifyAppStorageError} answers `null` rather than guessing, and why
+ * a block must branch on the CLASSIFICATION and render its OWN copy — see the
+ * warning on that function.
+ *
+ * One consequence worth stating plainly: `null` is a **BUSY** bucket, and its
+ * dominant real-world occupant is an expired or revoked token, not a rare
+ * unknown. Do not write a `default:` arm that assumes `null` means "transient,
+ * retry" — see the warning on {@link classifyAppStorageError}.
+ *
+ * ## Which ceiling each message names
+ *
+ * Two scopes, and the remedies differ:
+ *
+ * - **per-user** (`'per-user storage quota exceeded'`, `'per-user row limit
+ *   exceeded'`) — this viewer has filled their own budget for this app. The
+ *   ceilings are `APP_STORAGE_MAX_BYTES` / `APP_STORAGE_MAX_ROWS`;
+ *   the viewer can free space by deleting their own rows.
+ * - **app-wide** (`'app quota exceeded'`, `'app row limit exceeded'`) — the
+ *   app has filled a far larger umbrella shared across every viewer. One
+ *   viewer's delete will not reliably clear it; this is the developer's
+ *   problem, and `appStorageLimits.ts` deliberately does not export the
+ *   umbrella's value because nothing reports usage against it.
+ *
+ * A block will normally hit the per-user pair. Both are reachable, so a
+ * matcher that handles only one is a matcher with a silent hole.
+ */
+/**
+ * The host's per-value-cap message, as a function of the cap — a mirror of the
+ * template literal at `apps.router.ts:569`, which divides by 1024 and appends
+ * `KB cap`.
+ *
+ * 🔴 **THIS IS A TEMPLATE ON THE HOST, SO IT IS A TEMPLATE HERE.** Writing
+ * `'value exceeds 64KB cap'` as a literal would be true only while the cap is
+ * 64KB, and a string that silently stops matching the host the day the cap
+ * moves is the exact defect #343 is about — one spelling that drifts, with
+ * nothing able to notice. Derived from {@link APP_STORAGE_MAX_VALUE_BYTES} so
+ * the two move together.
+ *
+ * Exported from this module (not from `@civitai/app-sdk/blocks`) so a test can
+ * feed it a cap the constant cannot equal and watch the output move. Blocks
+ * want {@link APP_STORAGE_ERROR_VALUE_TOO_LARGE}.
+ */
+export declare function appStorageValueTooLargeMessage(capBytes?: number): string;
+/**
+ * A single value exceeded the per-value wire cap
+ * ({@link APP_STORAGE_MAX_VALUE_BYTES}). `apps.router.ts:568-569`.
+ *
+ * The only one of the six ceiling messages that is not a fixed string on the
+ * host — see {@link appStorageValueTooLargeMessage}.
+ */
+export declare const APP_STORAGE_ERROR_VALUE_TOO_LARGE: string;
+/** The APP-wide byte umbrella is full. `apps.router.ts:782-785`. */
+export declare const APP_STORAGE_ERROR_APP_QUOTA_EXCEEDED = "app quota exceeded";
+/** The APP-wide row umbrella is full. `apps.router.ts:790-793`. */
+export declare const APP_STORAGE_ERROR_APP_ROW_LIMIT = "app row limit exceeded";
+/**
+ * This viewer's byte budget for this app (`APP_STORAGE_MAX_BYTES`) is
+ * full. `apps.router.ts:844-847`.
+ */
+export declare const APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED = "per-user storage quota exceeded";
+/**
+ * This viewer's row budget for this app (`APP_STORAGE_MAX_ROWS`) is
+ * full. `apps.router.ts:852-855`.
+ *
+ * The ceiling a block reaches first in practice: rows run out long before
+ * bytes do.
+ */
+export declare const APP_STORAGE_ERROR_USER_ROW_LIMIT = "per-user row limit exceeded";
+/**
+ * The bridge's fallback, used for any storage failure whose error carries no
+ * usable message — a transport fault, a non-`Error` throw, an upstream 5xx.
+ * `IframeHost.tsx:287`.
+ *
+ * 🔴 It is NOT specific to writes. Every `APP_STORAGE_*` catch arm goes
+ * through the same helper, so a `get`, `delete`, `list` or `getQuota` can
+ * reject with it too. Retryable, unlike the five ceilings.
+ */
+export declare const APP_STORAGE_ERROR_REQUEST_FAILED = "storage request failed";
+/**
+ * The **`PAYLOAD_TOO_LARGE` family** — one string per `PAYLOAD_TOO_LARGE` site
+ * in `apps.router.ts` — plus the bridge's fallback, as of the measurement in
+ * this file's header.
+ *
+ * 🔴 **NOT "every ceiling string the host can put on the wire", and NOT "every
+ * string a block can receive".** Two separate reasons, and both are load-
+ * bearing:
+ *
+ *   - The bridge's catch arms are blanket, so every other rejection the host
+ *     raises arrives on the SAME field and is absent here on purpose. `invalid
+ *     block token`, `block instance revoked`, `Apps are not enabled` and the
+ *     `storage … scope` template are examples of what that covers —
+ *     **illustrations, not a bound.** See this file's header for why no list
+ *     of them lives in this repository.
+ *   - 🔴 The host also enforces **size ceilings zod-side** (`key` capped at 200
+ *     characters on the `.input()` schema, and three more on `list`). Those
+ *     throw no `TRPCError`, so they are invisible to the re-derivation recipe
+ *     AND absent from this array, while being ceilings in every sense a block
+ *     cares about. See "Ceilings outside this set" in this file's header.
+ *
+ * This is the set `createMockHost` and the starter harnesses must draw from —
+ * enforced by `tests/guards/app-storage-error-strings.test.mjs`, so a
+ * hand-typed string cannot reappear at a mock rejection site.
+ *
+ * 🔴 **NOT RE-EXPORTED FROM `@civitai/app-sdk/blocks`, ON PURPOSE.** Publishing
+ * this array invites `APP_STORAGE_HOST_ERROR_MESSAGES.includes(err.message)`,
+ * which is EQUALITY against a frozen snapshot — narrower than
+ * {@link isAppStorageHostErrorMessage}, and narrower than
+ * {@link classifyAppStorageError}, by exactly the per-value message, whose cap
+ * the host is free to move. That is the matcher shape #343 exists to
+ * eliminate, so it must not become public API. Reach it by file path from a
+ * test or a guard; a block branches on the classifier's reason.
+ *
+ * 🔴 **A CLOSED SET IS A CLAIM ABOUT A MEASUREMENT, NOT A CONTRACT — and this
+ * measurement is narrow by construction, not merely stale.** Three separate
+ * gaps, and only the first is about the future:
+ *
+ *   1. The host can add a `PAYLOAD_TOO_LARGE` site or reword an existing one
+ *      in any deploy, and nothing here will notice.
+ *   2. **Today, already**, every non-ceiling rejection the host raises reaches
+ *      the block on the same field and is not in this array. 🔴 This is not a
+ *      hole to be filled — two drafts tried and both came up short (see this
+ *      file's header). Those strings are the host's session, approval and
+ *      feature-flag prose, not ceiling vocabulary, and enumerating them here
+ *      would invite exactly the equality matching the rest of this comment
+ *      argues against.
+ *   3. 🔴 **Today, already, a SIZE ceiling the host enforces is missing from
+ *      here too** — the zod caps, which are not `TRPCError` throws at all.
+ *      Unlike gap 2 this one IS ceiling vocabulary, which is why the array's
+ *      scope is spelled as "the `PAYLOAD_TOO_LARGE` family" above rather than
+ *      as "the ceilings". See "Ceilings outside this set" in this file's
+ *      header.
+ *
+ * So an unrecognised string is "some storage failure, unknown which" — NOT
+ * "some ceiling", and never "impossible".
+ */
+export declare const APP_STORAGE_HOST_ERROR_MESSAGES: readonly [string, "app quota exceeded", "app row limit exceeded", "per-user storage quota exceeded", "per-user row limit exceeded", "storage request failed"];
+/**
+ * Which rejection site a storage failure came from, as a closed set. `null`
+ * means the string matched nothing known — see {@link classifyAppStorageError}.
+ */
+export type AppStorageRejectionReason = 'value-too-large' | 'app-quota-exceeded' | 'app-row-limit' | 'user-quota-exceeded' | 'user-row-limit' | 'request-failed';
+/**
+ * Turn a rejection — the `Error` `useAppStorage().set()` throws, or its raw
+ * message — into the rejection site it came from, or `null` when the string
+ * matches nothing this SDK version knows about.
+ *
+ * Branch on the RESULT; render your OWN copy.
+ *
+ * 🔴 **NEVER RENDER THE MESSAGE ITSELF TO A VIEWER.** It is host-authored
+ * server prose in the same class as a workflow `snapshot.error`: not
+ * localized, not written for an end user, and free to change. Log it for
+ * yourself (`console.warn`) and show copy your app owns.
+ *
+ * 🔴 **`null` IS A REAL OUTCOME, NOT AN ERROR IN YOUR CODE — AND IT DOES NOT
+ * MEAN "TRANSIENT".** THREE different things land here, and only one is a
+ * retry:
+ *
+ *   - a ceiling message this SDK version has not seen (the host reworded one,
+ *     or added a site, and your block compiled against an older SDK);
+ *   - 🔴 **and, far more often in production, an authorization or kill-switch
+ *     failure.** The bridge's catch arms are blanket, so every other rejection
+ *     the host raises arrives on the same field and classifies `null` — for
+ *     example `invalid block token` (an expired token mid-session), `block
+ *     instance revoked`, `storage set requires the apps:storage:write scope`,
+ *     or `Apps are not enabled` (the feature flag, which fires before anything
+ *     else on every storage call). 🔴 **Those are ILLUSTRATIONS, not the set**:
+ *     see this module's header for why no list of them lives here.
+ *   - 🔴 **and a zod INPUT-VALIDATION refusal, which never reaches a handler at
+ *     all.** tRPC parses `.input()` before the procedure body, so a bound
+ *     violated there is a `BAD_REQUEST` with a zod-generated message — no
+ *     `TRPCError` anywhere in the router, and nothing this module classifies.
+ *     The one a real block hits: the host caps `key` at **200 characters**
+ *     (`z.string().min(1).max(200)`), and neither `useAppStorage` nor
+ *     `createMockHost` caps it locally, so a key derived from a URL or a model
+ *     name can save fine under `dev:mock` and fail forever in production. 🔴
+ *     **A RELOAD DOES NOT FIX THAT ONE** — see "Ceilings outside this set" in
+ *     this module's header.
+ *
+ * So **"Please try again" is the wrong copy for the `null` arm.** Retrying an
+ * expired token forever is the failure this warning exists to prevent. Write a
+ * generic arm that offers a RELOAD (which re-mints the token, and also covers
+ * a genuine transport blip) and concedes that saving may be unavailable — and
+ * keep `'request-failed'` separate if you want honest retry copy, since that
+ * reason really is the transport one.
+ *
+ * @example
+ * try {
+ *   await storage.set(key, note);
+ * } catch (err) {
+ *   console.warn('[my-app] save failed:', err);
+ *   switch (classifyAppStorageError(err)) {
+ *     case 'value-too-large':
+ *       return 'That note is too long to save. Try shortening it.';
+ *     case 'user-row-limit':
+ *     case 'app-row-limit':
+ *       return 'You have no note slots left. Delete one to make room.';
+ *     case 'request-failed':
+ *       // The bridge's fallback: genuinely a transport fault. Retry is honest.
+ *       return 'Could not save that note. Please try again.';
+ *     default:
+ *       // `null`: an unknown ceiling OR — usually — an expired/revoked token.
+ *       return 'Could not save that note. Try reloading the page; if it keeps ' +
+ *         'happening, saving may be unavailable for this app right now.';
+ *   }
+ * }
+ */
+export declare function classifyAppStorageError(error: unknown): AppStorageRejectionReason | null;
+/**
+ * Is `message` one of the `PAYLOAD_TOO_LARGE`-family strings above (or the
+ * bridge's fallback)?
+ *
+ * 🔴 Not "a string the host can produce", and not "a ceiling" either — it
+ * answers `false` for every non-ceiling rejection the host raises, all of which
+ * the host produces and the bridge forwards on the same field, AND for the
+ * host's zod-enforced size caps, which are ceilings it does not know about (see
+ * "Ceilings outside this set" in this file's header). It is a membership test
+ * over {@link APP_STORAGE_HOST_ERROR_MESSAGES}, nothing wider.
+ *
+ * Wider than `APP_STORAGE_HOST_ERROR_MESSAGES.includes(…)` by exactly one
+ * case: the per-value message is a template on the host, so any cap spelling
+ * is admitted — see {@link classifyAppStorageError}.
+ *
+ * Module-internal, like the array: it is a `classifyAppStorageError(…) !== null`
+ * convenience for `tests/guards/app-storage-error-strings.test.mjs`, which
+ * imports this file by PATH. A block wants the classifier's reason, not a
+ * yes/no on host prose.
+ */
+export declare function isAppStorageHostErrorMessage(message: unknown): message is string;
+//# sourceMappingURL=appStorageErrors.d.ts.map